frsh_core.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
  59 //==============================================
  60 //  ******** *******    ********  **      **
  61 //  **///// /**////**  **//////  /**     /**
  62 //  **      /**   /** /**        /**     /**
  63 //  ******* /*******  /********* /**********
  64 //  **////  /**///**  ////////** /**//////**
  65 //  **      /**  //**        /** /**     /**
  66 //  **      /**   //** ********  /**     /**
  67 //  //       //     // ////////   //      //
  68 //
  69 // FRSH(FRescor ScHeduler), pronounced "fresh"
  70 //==============================================
  71
  72 #ifndef _FRSH_CORE_H_
  73 #define _FRSH_CORE_H_
  74
  75
  76 /**
  77  * @file frsh_core.h
  78  *
  79  * This file contains the types, definitions and function prototypes
  80  * for the core module of the FRescor ScHeduler.
  81  **/
  82
  83
  84 #include <time.h>
  85 #include <pthread.h>
  86 #include <sys/types.h>
  87
  88 #include "frsh_core_types.h"
  89 #include "frsh_spare_capacity.h"
  90
  91 /**
  92  * @defgroup core Core module
  93  *
  94  * This module includes the basic functions and services that are
  95  * provided by any FRSH implementation. This module includes basic type
  96  * definitions, and functions to
  97  *
  98  * - create a contract and initialize it
  99  * - set/get the basic parameters of a contract
 100  * - negotiate a service contract, obtaining a vres id
 101  * - create and bind threads to vres
 102  * - create/destroy a synchronization object
 103  * - manage bounded workloads
 104  *
 105  **/
 106
 107
 108 //////////////////////////////////////////////////////////////////////
 109 //           INITIALIZATION SERVICES
 110 //////////////////////////////////////////////////////////////////////
 111
 112 /**
 113  * @defgroup initialization Initialization services
 114  * @ingroup core
 115  *
 116  * These functions need to be called before doing any FRSH operation
 117  * (including contract initialization).
 118  *
 119  * @{
 120  **/
 121
 122
 123 /**
 124  * frsh_init()
 125  *
 126  * We cannot call any frsh functions before frsh_init. After calling
 127  * frsh_init, the main will be executing in the background. Then, it
 128  * can do the negotiations and create new threads if needed.  The
 129  * second time this function is called it fails.
 130  *
 131  * @return
 132  *  FRSH_ERR_SYSTEM_ALREADY_INITIALIZED : if the function has already
 133  *                                        been called before
 134  *
 135  *  It may also return any of the errors that may be returned by the
 136  *  underlying operating system primitives required to perform the
 137  *  FRSH system start up
 138  *
 139  **/
 140 int frsh_init();
 141
 142 /*@}*/
 143
 144
 145 /////////////////////////////////////////////////////////////
 146 //                       CONTRACT PARAMETERS
 147 /////////////////////////////////////////////////////////////
 148 /**
 149  * @defgroup contract Contract Creation and Initialization.
 150  * @ingroup core
 151  *
 152  * These functions are used to create and initialize a contract, and
 153  * set its parameters.
 154  *
 155  * @{
 156  **/
 157
 158
 159
 160 /**
 161  * frsh_contract_init()
 162  *
 163  * The operation receives a pointer to a contract object
 164  * and initializes it, setting it to the default values.
 165  *
 166  * The default values are:
 167  *
 168  * - resource_id               => 0
 169  * - ressource_type            => FRSH_CRT_PROCESSOR
 170  * - contract_id               =>
 171  * - budget_min                => {0,0};
 172  * - period_max                => {0,0};
 173  * - budget_max                => {0,0};
 174  * - period_min                => {0,0};
 175  * - workload                  => DEFAULT_WORKLOAD => FRSH_INDETERMINATE
 176  * - d_equals_t                => DEFAULT_D_EQUALS_T; (false or true)
 177  * - contract_type             => FRSH_CT_REGULAR;
 178  * - deadline                  => DEFAULT_DEADLINE;
 179  * - budget_overrun_sig_notify => 0;  (signal number)
 180  * - budget_overrun_sig_value  => {0, NULL};
 181  * - deadline_miss_sig_notify  => 0;  (signal number)
 182  * - deadline_miss_sig_value   => {0, NULL};
 183  *
 184  * - granularity               => DEFAULT_GRANULARITY;
 185  * - utilization_set;          => size = 0
 186  * - quality                   => DEFAULT_QUALITY;    (range 0..100)
 187  * - importance                => DEFAULT_IMPORTANCE; (range 1..5)
 188  * - preemption_level          => 0; (range 1..2**32-1)
 189  * - critical_sections;        => size = 0
 190  *
 191  * - sched_policy              => DEFAULT_SCHED_POLICY (FRSH_NONE)
 192  *
 193  * @param     contract the pointer to the contract variable.
 194  *
 195  * @return    FRSH_ERR_BAD_ARGUMENT :  contract is NULL
 196  *
 197  **/
 198 int frsh_contract_init(frsh_contract_t *contract);
 199
 200
 201 /**
 202  * frsh_contract_set_basic_params()
 203  *
 204  * The operation updates the specified contract parameters object by
 205  * setting its budget, period, workload and type to the specified
 206  * input parameters. (Note: the workload is a basic parameter because
 207  * bounded tasks are triggered by the scheduler (see the
 208  * frsh_timed_wait() and frsh_synchobj_wait* operations), while
 209  * indeterminate tasks are not; therefore, their programming model is
 210  * quite different).
 211  *
 212  * @param contract     the pointer to the contract object
 213  * @param[in] budget_min   the minimum budget for the contract
 214  * @param[in] period_max   the maximum period for the contract
 215  * @param[in] workload     the kind of workload (can be FRSH_BOUNDED,
 216  *                            FRSH_INDETERMINATE or FRSH_OVERHEAD)
 217  * @param[in] contract_type can be FRSH_CT_REGULAR,
 218  *                                 FRSH_CT_BACKGROUND, FRSH_CT_DUMMY.
 219  *
 220  * @return 0 if the operation is succesful
 221  *    FRSH_ERR_BAD_ARGUMENT :  if any of the pointers is NULL
 222  *    or if only one of the timespec values is 0, and also if the
 223  *    workload or the contract type values are unknown in the
 224  *    enumerations.
 225  **/
 226 int frsh_contract_set_basic_params
 227   (frsh_contract_t *contract,
 228    const char *contract_id,
 229    const struct timespec     *budget_min,
 230    const struct timespec     *period_max,
 231    frsh_workload_t            workload,
 232    frsh_contract_type_t       contract_type);
 233
 234 /**
 235  * frsh_get_contract_basic_params()
 236  *
 237  * This operation obtains from the specified contract object its
 238  * budget, period, and workload, and copies them to the places pointed
 239  * to by the corresponding output parameters.
 240  *
 241  * @param[in] contract   the pointer to the contract object
 242  * @param[out] budget_min pointer to preallocated space
 243  * @param[out] period_max pointer to preallocated space
 244  * @param[out] workload pointer to preallocated space
 245  * @param[out] contract_type pointer to preallocated space
 246  *
 247  * @return   FRSH_ERR_BAD_ARGUMENT :  if one of the contract or
 248  *                                    pointers is NULL.
 249  *
 250  **/
 251 int frsh_contract_get_basic_params
 252   (const frsh_contract_t *contract,
 253    char *contract_id,
 254    struct timespec  *budget_min,
 255    struct timespec  *period_max,
 256    frsh_workload_t   *workload,
 257    frsh_contract_type_t *contract_type);
 258
 259 /**
 260  * frsh_contract_set_resource_type_and_id()
 261  *
 262  * Specify processor_id/network_id and whether it is a processor or a
 263  * network.  Otherwise default values (type is processor and id is #0
 264  * will apply.
 265  **/
 266 int frsh_contract_set_resource_type_and_id
 267   (frsh_contract_t *contract,
 268    frsh_resource_id_t resource_id,
 269    frsh_resource_type_t resource_type);
 270
 271
 272 /**
 273  * frsh_contract_get_resource_type_and_id()
 274  *
 275  * Specify processor_id/network_id and whether it is a processor or a
 276  * network.  Otherwise default values (processor and processor #0 will
 277  * apply.
 278  **/
 279 int frsh_contract_get_resource_type_and_id
 280   (const frsh_contract_t *contract,
 281    frsh_resource_id_t *resource_id,
 282    frsh_resource_type_t *resource_type);
 283
 284
 285 /**
 286  * frsh_contract_set_timing_req()
 287  *
 288  * The operation updates the specified contract object, specifying
 289  * additional time-related requirements.
 290  *
 291  * @param  contract The pointer to the contract object
 292  *
 293  * @param [in] d_equals_t It is a boolean value, set to true (1) if
 294  *                        we want to specify a deadline different from
 295  *                        the period  for the contract.
 296  * @param [in] deadline  If the previous parameter is set to true,
 297  *                       this parameter is ignored (the contract value
 298  *                       will be NULL_DEADLINE internally). Otherwise, it
 299  *                       contains the desired deadline value.
 300  * @param [in] budget_overrun_sig_notify contains the number of the signal
 301  *                that must be raised if the budget of the vres is overrun.
 302  *                If the value of this parameter is FRSH_NULL_SIGNAL, no signal will
 303  *                be raised.
 304  * @param [in] budget_overrun_sig_value contains the value that will be
 305  *               passed to the signal "catcher" when the signal is raised.
 306  *               This parameters is not used if the budget_overrun_sig_notify
 307  *               parameter is set to FRSH_NULL_SIGNAL.
 308  * @param [in] deadline_miss_sig_notify contains the number of the
 309  *               signal that must be raised if the deadline of the
 310  *               vres is missed. If the value of this parameter is
 311  *               FRSH_NULL_SIGNAL, no signal is raised.
 312  * @param [in] deadline_miss_sig_value contains the value that will be
 313  *                passed to the signal "catcher" when the signal is
 314  *                raised.  This parameter is not used if the
 315  *                deadline_sig_notify parameter is set to NULL_SIGNAL
 316  *
 317  * @return  0 if successful
 318  *     FRSH_ERR_BAD_ARGUMENT :  if contract is NULL or
 319  *      (d_equals_t is true and  deadline is not FRSH_NULL_DEADLINE) or
 320  *      (budget_overrun_sig_notify is not a valid signal)  or
 321  *      (deadline_miss_sig_notify is not a valid signal)  or
 322  *      (d_equals_t is false but (deadline is FRSH_NULL_DEADLINE or its value
 323  *                                is grater than the contract's maximum period))
 324  *
 325  **/
 326 int frsh_contract_set_timing_req
 327   (frsh_contract_t *contract,
 328    bool                   d_equals_t,
 329    const struct timespec *deadline,
 330    frsh_signal_t          budget_overrun_signal,
 331    frsh_signal_info_t     budget_overrun_siginfo,
 332    frsh_signal_t          deadline_miss_signal,
 333    frsh_signal_info_t     deadline_miss_siginfo);
 334
 335 /**
 336  * frsh_contract_get_timing_req()
 337  *
 338  * The operation obtains the corresponding input parameters from the
 339  * specified contract object. If d_equals_t is true, the deadline will
 340  * be set to FRSH_NULL_DEADLINE.
 341  *
 342  * @return
 343  *   FRSH_ERR_BAD_ARGUMENT :  if contract is NULL
 344  *
 345  **/
 346 int frsh_contract_get_timing_req
 347   (const frsh_contract_t *contract,
 348    bool                    *d_equals_t,
 349    struct timespec         *deadline,
 350    frsh_signal_t           *budget_overrun_signal,
 351    frsh_signal_info_t      *budget_overrun_siginfo,
 352    frsh_signal_t           *deadline_miss_signal,
 353    frsh_signal_info_t      *deadline_miss_siginfo);
 354
 355
 356 /*@}*/
 357
 358 //////////////////////////////////////////////////////////////////
 359 //                 SYNCHRONIZATION OBJECTS
 360 //////////////////////////////////////////////////////////////////
 361 /**
 362  * @defgroup synch  Synchronization objects
 363  * @ingroup core
 364  *
 365  * Synchronisation objects provide an alternative to timers for
 366  * bounded-workload vres to signal the end of their current job and
 367  * return their remaining budget to FRSH.
 368  *
 369  * Instead of asking to be reactivated based on an absolute time, they
 370  * queue themselves in a synchronisation object and will wait there
 371  * until another vres (bounded-workload or indeterminate-workload)
 372  * wakes them up with a signal call the earliest at the beginning of
 373  * the next period.
 374  *
 375  * Indeterminate-workload vres cannot queue themselves here because
 376  * they don't have any budget to return.  However they can signal on
 377  * the objects to activate a waiting workload vres.
 378  *
 379  * For classical signal/wait synchronisation paradigms the application
 380  * must use whatever mechanism the underlying OS provides.
 381  *
 382  * In the future we may add a broadcast operation that would signal a
 383  * group of synchronization objects. We have not included a broadcast
 384  * service in this version because it can be easily created by the
 385  * user by signalling individual synchronization objects inside a
 386  * loop.
 387  *
 388  * Notice that for synchronization objects there is no naming service
 389  * like in shared objects because tasks that use synchronization are
 390  * not developed independently, as they are closely coupled.
 391  *
 392  * @{
 393  **/
 394
 395
 396 /**
 397  * frsh_synchobj_create()
 398  *
 399  * This operation creates and initializes a synchronization object
 400  * variable managed by the scheduler, and returns a handle to it in
 401  * the variable pointed to by synch_handle.
 402  *
 403  * @param[out]  pointer to the variable that will contain the handle to the
 404  *              newly created synchronization object
 405  *
 406  * @return
 407  *   FRSH_ERR_BAD_ARGUMENT :  if synch_handle is 0
 408  *   FRSH_ERR_TOO_MANY_SYNCH_OBJS : if the number of synchronization
 409  *      objects in the system has already exceeded the maximum
 410  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 411  *      scheduled under the FRSH
 412  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 413  *
 414  **/
 415 int frsh_synchobj_create
 416     (frsh_synchobj_handle_t *synch_handle);
 417
 418
 419 /**
 420  * frsh_synchobj_destroy()
 421  *
 422  * This operation destroys the synchronization object (created by a
 423  * previous call to frsh_create_synch_obj) that is referenced by the
 424  * synch_handle variable. After calling this operation, the
 425  * synch_handle variable can not be used until it is initialized again
 426  * by a call to frsh_create_synch_obj.
 427  *
 428  * @param synch_handle the handle to the synchronization object
 429  *            to be destroyed
 430  *
 431  * @return 0 if the operation is succesful
 432  *   FRSH_ERR_BAD_ARGUMENT :  if synch_handle is 0
 433  *   FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
 434  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 435  *                                             scheduled under the FRSH
 436  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 437  *
 438  * @sa frsh_synchobj_create
 439  **/
 440 int frsh_synchobj_destroy
 441     (frsh_synchobj_handle_t synchobj_handle);
 442
 443 /**
 444  * frsh_synchobj_wait()
 445  *
 446  * This operation is invoked by threads associated with bounded
 447  * workload vres to indicate that a job has been completed (and
 448  * that the scheduler may reassign the unused capacity of the current
 449  * job to other vres).
 450  *
 451  * As a difference with frsh_timed_wait(), here the server
 452  * specifies to be awakened by the arrival of a signal operation
 453  * instead of at a precise point of time.
 454  *
 455  * This function can also be called to schedule the first job of a
 456  * recently created vres and make it start when a signal operation
 457  * has been sent from another thread.
 458  *
 459  * The vres' budget will be made zero for the remainder of the vres'
 460  * period, and FRSH will not replenish it until an event has been
 461  * notified to the synchronisation object by another vres.
 462  *
 463  * It can happen that the synchronisation object has notification
 464  * events queued from the past, in this case one of the events is
 465  * dequeued immediately and the vres won't have to wait for another
 466  * one.
 467  *
 468  * At the time of reception of a notification event (wether in the
 469  * future or in the past), all pending budget replenishments (if any)
 470  * are made effective. Once the vres has a positive budget and the
 471  * scheduler schedules the calling thread again, the call returns and
 472  * the vres continues executing.
 473  *
 474  * If the synchronisation object is destroyed while the vres was
 475  * waiting on it, the vres will be awaken and the function will
 476  * return with a code FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE
 477  *
 478  * Except for those parameters equal to NULL pointers, the system
 479  * reports the current period and budget for the current job, it informs
 480  * if the deadline of the previous job was missed or not, and whether the
 481  * budget of the previous job was overrun or not.
 482  *
 483  * In a system with hierarchical scheduling, since this call makes the
 484  * budget of the current period zero, the other threads in the same
 485  * vres are not run. As mentioned above, only when the call finishes
 486  * the budget may be replenished.
 487  *
 488  * @param synch_handle   Synchronisation object upon which the vres
 489  *                       will be waiting.
 490  * @param next_budget[out]  Upon return of this function, the variable
 491  *                          pointed by this function will be equal to
 492  *                                      the current vres budget. If this parameter is
 493  *                                      set to NULL, no action is taken
 494  * @param next_period[out]  The vres period upon return (ignored if NULL).
 495  * @param was_deadline_missed Upon return whether the deadline was
 496  *                           missed in the previous period.
 497  * @param was_budget_overran
 498  *
 499  *
 500  * @return 0 if success
 501  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 502  *   FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 503  *     main scheduler
 504  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
 505  *     under the FRSH
 506  *   FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid vres bound to it
 507  *   FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0
 508  *   FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the synch_handle is not
 509  *                 valid or was destroyed while the vres was waiting on it.
 510  *   FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the vres
 511  *     is not FRSH_BOUNDED
 512  *
 513  **/
 514 int frsh_synchobj_wait
 515   (frsh_synchobj_handle_t  synch_handle,
 516    struct timespec         *next_budget,
 517    struct timespec         *next_period,
 518    bool                    *was_deadline_missed,
 519    bool                    *was_budget_overran);
 520
 521
 522 /**
 523  * frsh_synchobj_wait_with_timeout()
 524  *
 525  * This call is the same as frsh_synchobj_wait() but with an extra
 526  * absolute timeout. The timed_out argument, indicates whether the
 527  * function returned because of the expiration of the timeout or not.
 528  *
 529  * @return
 530  *   FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the synch_handle is not valid
 531  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 532  *   FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 533  *     main scheduler
 534  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
 535  *     under the FRSH
 536  *   FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid
 537  *     vres bound to it
 538  *   FRSH_ERR_BAD_ARGUMENT :  if the synch_handle given is not valid or the
 539  *     abs_timeout argument is NULL or its value is in the past
 540  *   FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the vres
 541  *     is not FRSH_BOUNDED
 542  *
 543  **/
 544 int frsh_synchobj_wait_with_timeout
 545   (frsh_synchobj_handle_t  synch_handle,
 546    const struct timespec   *abs_timeout,
 547    bool                    *timed_out,
 548    struct timespec         *next_budget,
 549    struct timespec         *next_period,
 550    bool                    *was_deadline_missed,
 551    bool                    *was_budget_overran);
 552
 553 /**
 554  * frsh_synchobj_signal()
 555  *
 556  * This function sends a notification event to the synchronization object
 557  * specified as parameter. If there is at least one vres waiting on
 558  * the synchronization object, it is awaken. If more than one vres
 559  * are waiting, just one of them is awaken. However, which one is
 560  * awaken is implementation dependent. If no vres is waiting on the
 561  * synchronization object, the notification event is queued.
 562  *
 563  * @param [in] synch_handle the handle of the synchronization object to
 564  *                 notify.
 565  *
 566  * @return 0 if the operation is completed succesfully
 567  *    FRSH_ERR_BAD_ARGUMENT :  if synch_handle is 0
 568  *    FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
 569  *    FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 570  *            scheduled under the FRSH
 571  *    FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 572  *    FRSH_ERR_TOO_MANY_EVENTS_IN_SYNCH_OBJ : if the number of events stored
 573  *            in the synchronization object reaches the maximum defined in the
 574  *      configuration parameter header file
 575  *
 576  * @sa frsh_synchobj_wait, frsh_synchobj_wait_with_timeout
 577  **/
 578 int frsh_synchobj_signal
 579     (frsh_synchobj_handle_t synch_handle);
 580
 581 /**
 582  * frsh_timed_wait()
 583  *
 584  * This operation is invoked by threads associated with bounded
 585  * workload vres to indicate that a job has been completed (and
 586  * that the scheduler may reassign the unused capacity of the current
 587  * job to other vres). It is also invoked when the first job of
 588  * such threads has to be scheduled.
 589  *
 590  * As an effect, the system will make the current vres's budget zero
 591  * for the remainder of the vres's period, and will not replenish
 592  * the budget until the specified absolute time.  At that time, all
 593  * pending budget replenishments (if any) are made effective. Once the
 594  * server has a positive budget and the scheduler schedules the
 595  * calling thread again, the call returns and at that time, except for
 596  * those parameters equal to NULL pointers, the system reports the
 597  * current period and budget for the current job, whether the deadline
 598  * of the previous job was missed or not, and whether the budget of
 599  * the previous job was overrun or not.
 600  *
 601  * In a system with hierarchical scheduling, since this call makes the
 602  * budget zero, the other threads in the same server are not run. As
 603  * mentioned abobe, only when the call finishes the budget may be
 604  * replenished.
 605  *
 606  *  * @param [in] abs_time     absolute time at which the budget will be
 607  *                          replenished
 608  *
 609  * @param [out] next_budget upon return of this function, the variable
 610  *                          pointed by this function will be equal to
 611  *                          the current server budget. If this parameter is
 612  *                          set to NULL, no action is taken.
 613  *
 614  * @param [out] next_period upon return of this function, the variable
 615  *                          pointed by this function will be equal to
 616  *                          the current server period. If this parameter is
 617  *                          set to NULL, no action is taken.
 618  *
 619  * @param [out] was_deadline_missed upon return of this function, the
 620  *                          variable pointed by this function will be
 621  *                          equal to true if the previous server deadline
 622  *                          was missed, to false otherwise. If this
 623  *                          parameter is set to NULL, no action is
 624  *                          taken.
 625  *
 626  * @param [out] was_budget_overrun upon return of this function, the
 627  *                          variable pointed by this function will be
 628  *                          equal to true if the previous server budget was
 629  *                          overrun, to false otherwise. If this
 630  *                          parameter is set to NULL, no action is
 631  *                          taken.
 632  *
 633  * @return  0 if the operation is succesful
 634  *          FRSH_ERR_TIME_SPEC_IN_THE_PAST if the absolute time specification
 635  *            is in the past.
 636  *          FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 637  *          FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 638  *                                    main scheduler
 639  *          FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling
 640  *                      thread is not scheduled under the FRSH
 641  *   FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid
 642  *     server bound to it
 643  *   FRSH_ERR_BAD_ARGUMENT :  if abs_time is NULL
 644  *   FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the server
 645  *     is not FRSH_BOUNDED
 646  *
 647  *
 648  * @sa frsh_synchobj_wait, frsh_synchobj_wait_with_timeout
 649  **/
 650 int frsh_timed_wait
 651   (const struct timespec *abs_time,
 652    struct timespec       *next_budget,
 653    struct timespec       *next_period,
 654    bool                  *was_deadline_missed,
 655    bool                  *was_budget_overran);
 656
 657
 658 /*@}*/
 659
 660 ///////////////////////////////////////////////////////////////////
 661 //                 CONTRACT NEGOCIATION OPERATIONS
 662 ///////////////////////////////////////////////////////////////////
 663
 664 /**
 665  * @defgroup negotiate Negotiate contract functions
 666  * @ingroup core
 667  *
 668  * The following functions are used to negotiate contracts and thus
 669  * creating vres which are the execution image of a contract.
 670  * Besides, these functions allow to assign and unassign threads to
 671  * vres.
 672  *
 673  * In the case of more than one thread per vres please refer to the
 674  * hierarchical module.
 675  *
 676  * @{
 677  **/
 678
 679
 680
 681 /**
 682  * frsh_negotiate_contract()
 683  *
 684  * The operation negotiates a contract and if accepted it will return
 685  * a vres_id.  It will also check that the given contract_id is unique
 686  * within the node.
 687  *
 688  * If the on-line admission test is enabled, it determines whether the
 689  * contract can be admitted or not based on the current contracts
 690  * established in the system. Then it creates the vres and
 691  * recalculates all necessary parameters for the contracts already
 692  * present in the system.
 693  *
 694  * This is a potentially blocking operation, it returns when the
 695  * system has either rejected the contract, or admitted it and made it
 696  * effective. No thread is bound to the newly created vres, which
 697  * will be idle until a thread is bound to it via frsh_thread_bind()
 698  * or frsh_thread_create_and_bind().
 699  *
 700  * This operation can only be executed by threads that are already
 701  * bound to an active vres and therefore are being scheduled by the
 702  * frsh scheduler.
 703  *
 704  * @return 0 if successful
 705  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 706  *   FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 707  *     main scheduler
 708  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
 709  *     under the FRSH
 710  *   FRSH_ERR_BAD_ARGUMENT :  if the contract or vres arguments are NULL
 711  *   FRSH_ERR_TOO_MANY_VRES : if there is no space for more vres
 712  *     (the maximum number of them is already reached)
 713  *   FRSH_ERR_CONTRACT_ID_ALREADY_EXISTS : contract_id is not unique,
 714  *
 715  **/
 716 int frsh_negotiate_contract
 717   (const frsh_contract_t *contract,
 718    frsh_vres_id_t      *vres);
 719
 720 /**
 721  * frsh_thread_create_and_bind()
 722  *
 723  * This operation creates a thread and binds it to an existing vres.
 724  *
 725  * This is the preferred way to add threads to the application because
 726  * we make sure that the thread won't become unbound.
 727  *
 728  * The vres must not have any thread binded to it.  If you want to
 729  * bind more than one thread to the vres you must use the
 730  * hierarchical module.
 731  *
 732  * The frsh_thread_attr_t parameter is overwritten as necessary to
 733  * introduce the adequate scheduling policy and priority,  according
 734  * to the preemption level given in the contract and the
 735  * frsh_priority_map() function defined by the user.
 736  *
 737  * @param[in] vres_id       vres with which the thread will be bound.
 738  * @param[out] thread         frsh_thread_id returned by the system.
 739  * @param attr         pthread_attr taken and maybe corrected
 740  *                                by the system.  Ignored if NULL
 741  * @param[in] thread_code     Thread function (void func(void *) )
 742  *                                that will constitute the main of the
 743  *                                thread.
 744  * @param[in] arg             Argument for data to be passed at the
 745  *                            thread. Set to NUL if you don't want
 746  *                            to do anything like this.
 747  *
 748  * @return  0 if successful
 749  *   FRSH_ERR_BAD_ARGUMENT : if the contract or vres arguments are NULL
 750  *   FRSH_ERR_CONTRACT_REJECTED : if the contract is rejected.
 751  *
 752  *   It may also return all the errors that may be returned by the
 753  *     fosa_thread_create() function call
 754  *
 755  **/
 756 int frsh_thread_create_and_bind
 757   (frsh_vres_id_t     vres,
 758    frsh_thread_id_t            *thread,
 759    frsh_thread_attr_t       *attr,
 760    frsh_thread_code_t     thread_code,
 761    void                 *arg);
 762
 763
 764 /**
 765  * frsh_thread_create_in_background()
 766  *
 767  * This function creates a "background contract" that does not need to
 768  * be negotiated, creates a threads and binds to the new vres.
 769  *
 770  * This method is suggested as a way to initate components and
 771  * plugins.  The event that triggers the component activation should
 772  * arrive to an application thread that could use this function to
 773  * create a thread used in its initialisation.
 774  *
 775  * The attribute parameter is overwritten as necessary to introduce
 776  * the adequate scheduling policy and priority.
 777  *
 778  * @param[in]  thread_code   Function to be executed by the new
 779  *                           thread.
 780  * @param[in]  thread_arg    General pointer that will be passed to
 781  *                           the new thread as initialisation data.
 782  * @param attr               Pthread attribute with thread params
 783  * @param[in]  contract_id   Contract Id for the new vres.
 784  * @param[out] thread_id     Id of the new thread.
 785  * @param[out] vres_id       vres_id of the new vres.
 786  *
 787  * @return 0 if successful
 788  *   FRSH_ERR_BAD_ARGUMENT : Any problems with the argument
 789  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
 790  *     under the FRSH
 791  *   FRSH_ERR_CONTRACT_ID_ALREADY_EXISTS : contract_id is not unique,
 792  *   FRSH_ERR_TOO_MANY_VRES : if there is no space for more vres
 793  *     (the maximum number of them is already reached)
 794  *
 795  **/
 796 int frsh_thread_create_in_background
 797     (frsh_thread_code_t thread_code,
 798      const void *thread_arg,
 799      const char *contract_id,
 800      frsh_thread_attr_t *attr,
 801      frsh_thread_id_t *thread_id,
 802      frsh_vres_id_t *vres_id);
 803
 804
 805 /**
 806  * frsh_thread_bind()
 807  *
 808  * This operation associates a thread with a vres, which means that
 809  * it starts consuming the vres's budget  and is executed according
 810  * to the contract established for that vres. If the thread is
 811  * already bound to another vres, it is effectively unbound from it
 812  * and bound to the specified one.
 813  *
 814  * It fails if the vres's policy is different than FRSH_NONE, or if
 815  * there is already a thread bound to this vres.  In order to bind
 816  * more than one vres to the same thread you must use the
 817  * hierarchical module.
 818  *
 819  * Implementation dependent issue: In order to allow the usage of
 820  * application defined schedulers, the given thread must not have the
 821  * scheduling policy SCHED_APP and at the same time be attached to an
 822  * application scheduler different than the frsh scheduler.
 823  *
 824  * @return
 825  *   FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 826  *     main scheduler
 827  *   FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
 828  *     an application defined scheduler different than the frsh scheduler
 829  *   FRSH_ERR_BAD_ARGUMENT : if the vres value does not complain with the
 830  *     expected format or valid range or the given thread does not exist
 831  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the referenced vres is not valid
 832  *   FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
 833  *     of the vres is FRSH_OVERHEAD
 834  *   FRSH_ERR_ALREADY_BOUND : if the given vres has a thread already bound
 835  *
 836  **/
 837 int frsh_thread_bind
 838   (frsh_vres_id_t vres,
 839    frsh_thread_id_t      thread);
 840
 841
 842 /**
 843  * frsh_thread_unbind()
 844  *
 845  * This operation unbinds a thread from a vres.  Since threads with
 846  * no vres associated are not allowed to execute, they remain in a
 847  * dormant state until they are either eliminated or bound again.
 848  *
 849  * If the thread is inside a critical section the effects of this call
 850  * are deferred until the critical section is ended
 851  *
 852  * Implementation dependent issue: in the implementation with an
 853  * application scheduler, the thread is still attached to the frsh
 854  * scheduler, but suspended.
 855  *
 856  * @return 0 if successul
 857  *   FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 858  *     main scheduler
 859  *   FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist
 860  *   FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
 861  *     under the FRSH
 862  *   FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
 863  *     an application defined scheduler different than the frsh scheduler
 864  *   FRSH_ERR_NOT_BOUND : if the given thread does not have a valid
 865  *     vres bound to it
 866  **/
 867 int frsh_thread_unbind(frsh_thread_id_t thread);
 868
 869 /**
 870  * frsh_thread_get_vres_id()
 871  *
 872  * This operation stores the Id of the vres associated with the
 873  * specified thread in the variable pointed to by vres. It returns
 874  * an error if the thread does not exist, it is not under the control
 875  * of the scheduling framework, or is not bound.
 876  *
 877  * @return
 878  *   FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
 879  *     under the FRSH
 880  *   FRSH_ERR_NOT_BOUND : if the given thread does not have a valid
 881  *     vres bound to it
 882  *   FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist or the
 883  *     vres argument is NULL
 884  *
 885  **/
 886 int frsh_thread_get_vres_id(frsh_thread_id_t       thread,
 887                     frsh_vres_id_t *vres_id);
 888
 889 /**
 890  * frsh_vres_get_contract()
 891  *
 892  * This operation stores the contract parameters currently associated
 893  * with the specified vres in the variable pointed to by
 894  * contract. It returns an error if the vres_id is not recognised.
 895  *
 896  * @return 0 if no error
 897  *   FRSH_ERR_BAD_ARGUMENT :  if the contract argument is NULL or the value
 898  *     of the vres argument is not in range
 899  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 900  *     scheduled under the FRSH
 901  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 902  *   FRSH_ERR_NOT_CONTRACTED_VRES: if the vres of the calling thread
 903  *     has been cancelled or it is not valid
 904  *  ]
 905  **/
 906 int frsh_vres_get_contract
 907   (frsh_vres_id_t vres,
 908     frsh_contract_t *contract);
 909
 910 /**
 911  * frsh_vres_get_id_from_contract_id()
 912  *
 913  * This operation retrieves the vres_id whose contract_id
 914  * corresponds to the parameter. It returns an error if the
 915  * contract_id is not known.
 916  *
 917  * @return 0 if no error
 918  *   FRSH_ERR_BAD_ARGUMENT :  if the contract argument is NULL or the
 919  *     contract_id is NULL
 920  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 921  *     scheduled under the FRSH
 922  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 923  *   FRSH_ERR_CONTRACT_ID_UNKNOWN: if the contract_id is not known
 924  **/
 925 int frsh_vres_get_id_from_contract_id
 926   (frsh_contract_id_t contract_id,
 927    frsh_vres_id_t *vres);
 928
 929
 930
 931 /**
 932  * frsh_contract_cancel()
 933  *
 934  * The operation eliminates the specified vres
 935  * and recalculates all necessary parameters for the contracts
 936  * remaining in the system. This is a potentially blocking operation;
 937  * it returns when the system has made the changes effective.
 938  *
 939  * Note that the thread is not eliminated.  We leave the application
 940  * the option to either freeze it for a later use or bind it to
 941  * another vres.
 942  *
 943  * @return 0 if successful
 944  *   FRSH_ERR_BAD_ARGUMENT :  if the value of vres is not in range
 945  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 946  *     scheduled under the FRSH
 947  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 948  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 949  *     has been cancelled or it is not valid
 950  *
 951  **/
 952 int frsh_contract_cancel (frsh_vres_id_t vres);
 953
 954
 955 /**
 956  * frsh_contract_renegotiate_sync()
 957  *
 958  * The operation renegotiates a contract for an existing vres. If
 959  * the on-line admission test is enabled it determines whether the
 960  * contract can be admitted or not based on the current contracts
 961  * established in the system. If it cannot be admitted, the old
 962  * contract remains in effect and an error is returned. If it can be
 963  * admitted, it recalculates all necessary parameters for the
 964  * contracts already present in the system and returns zero. This is a
 965  * potentially blocking operation; it returns when the system has
 966  * either rejected the new contract, or admitted it and made it
 967  * effective.
 968  *
 969  *  @return 0 if successful
 970  *   FRSH_ERR_BAD_ARGUMENT :  if the new_contract argument is NULL or the
 971  *     value of the vres argument is not in range
 972  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 973  *     scheduled under the FRSH
 974  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 975  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 976  *     has been cancelled or it is not valid
 977  *   FRSH_ERR_REJECTED_CONTRACT : if the renegotiation fails
 978  *
 979  **/
 980 int frsh_contract_renegotiate_sync
 981   (const frsh_contract_t *new_contract,
 982    frsh_vres_id_t vres);
 983
 984
 985 /**
 986  * frsh_contract_renegotiate_async()
 987  *
 988  * The operation enqueues a renegotiate operation for an existing
 989  * vres, and returns immediately. The renegotiate operation is
 990  * performed asynchronously, as soon as it is practical; meanwhile the
 991  * system operation will continue normally. When the renegotiation is
 992  * made, if the on-line admission test is enabled it determines
 993  * whether the contract can be admitted or not based on the current
 994  * contracts established in the system. If it cannot be admitted, the
 995  * old contract remains in effect. If it can be admitted, it
 996  * recalculates all necessary parameters for the contracts already
 997  * present in the system.
 998  *
 999  * When the operation is completed, notification is made to the
1000  * caller, if requested, via a signal. The status of the operation (in
1001  * progress, admitted, rejected) can be checked with the
1002  * frsh_vres_get_renegotiation_status() operation.  The argument
1003  * sig_notify can be FRSH_NULL_SIGNAL (no notification), or any FRSH
1004  * signal value and in this case signal_info is to be sent with the signal.
1005  *
1006  * @param[in] new_contract   New contract parameters for the new
1007  *                           situation if approved.
1008  * @param[in] vres           vres_id on which to do the renegotiation.
1009  * @param[in] signal_to_notify  Signal number to use to notify vres of
1010  *                           the negotiation result.  If
1011  *                           FRSH_NULL_SIGNAL,  no signal will be raised.
1012  * @param[in] signal_info:   Associated info that will come with the
1013  *                           signal.  This parameter will be ignored
1014  *                           if signal_to_notify == FRSH_NULL_SIGNAL.
1015  *
1016  * @return
1017  *   FRSH_ERR_BAD_ARGUMENT :  if the new_contract argument is NULL, the
1018  *     value of the vres argument is not in range or sig_notify is
1019  *     neither NULL nor a valid POSIX signal
1020  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
1021  *     scheduled under the FRSH
1022  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
1023  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
1024  *     has been cancelled or it is not valid
1025  *
1026  **/
1027 int frsh_contract_renegotiate_async
1028   (const frsh_contract_t *new_contract,
1029    frsh_vres_id_t vres,
1030    frsh_signal_t                     signal_to_notify,
1031    frsh_signal_info_t                signal_info);
1032
1033
1034 /**
1035  * frsh_vres_get_renegotiation_status()
1036  *
1037  * The operation reports on the status of the last renegotiation
1038  * operation enqueued for the specified vres. It is callable even
1039  * after notification of the completion of such operation, if
1040  * requested.
1041  *
1042  * If the vres is not and has not been involved in any of the
1043  * frsh_contract_renegotiate_async() or frsh_group_change_mode_async()
1044  * operations, the status returned is FRSH_NOT_REQUESTED
1045  *
1046  * @return:
1047  *   FRSH_ERR_BAD_ARGUMENT :  if the renegotiation_status argument is
1048  *     NULL or the value of the server argument is not in range
1049  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
1050  *     scheduled under the FRSH
1051  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
1052  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the server of the calling thread
1053  *     has been cancelled or it is not valid
1054  *
1055  **/
1056 int frsh_vres_get_renegotiation_status
1057   (frsh_vres_id_t vres,
1058    frsh_renegotiation_status_t *renegotiation_status);
1059
1060 /*@}*/
1061
1062 ////////////////////////////////////////////////////////////////////////
1063 //           CHANGE OF MODE: GROUPS OF CONTRACTS
1064 ////////////////////////////////////////////////////////////////////////
1065 /**
1066  * @defgroup groupofcontracts Group of contracts
1067  * @ingroup core
1068  *
1069  * The following functions are used to negotiate atomically more than
1070  * one contract.  This allows to build complex applications by
1071  * splitting them in individual contracts that are negotiated
1072  * simultaneously and atomically.
1073  *
1074  * @{
1075  **/
1076
1077 /**
1078  * frsh_group_negotiate()
1079  *
1080  * This function negotiates atomically a group of new contracts
1081  * while giving the possibility of cancellling others.
1082  *
1083  * If the on-line admission test is enabled, FRSH analizes the
1084  * schedulability of the context that results in the new contract
1085  * situation with removed and added contracts.
1086  *
1087  * If the overall negotiation is successful, all actions will be taken
1088  * inmediatly:  the creation of new vres for the contract_up list
1089  * and the cancellation of the designated ones.
1090  *
1091  * If for any reason one of the contracts is not accepted, a
1092  * corresponding error will be returned and no actions will be taken,
1093  * the previous context will be preserved.
1094  *
1095  * This call is a synchronous, potentially blocking operation.  It
1096  * returns when the system has rejected the contracts or accepted them
1097  * and made them effective.
1098  *
1099  * @param[in] contracts_up   List of new proposed contracts
1100  *
1101  * @param[in] vres_down   List of vres_id to be canceled
1102  *
1103  * @param[out] vres_up    vres_id assigned by the system to the
1104  *                           corresponding contracts_up.
1105  *
1106  * @return 0 if no error
1107  *
1108  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
1109  *   FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
1110  *      main scheduler
1111  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
1112  *      under the FRSH
1113  *   FRSH_ERR_BAD_ARGUMENT :  if any of the vres_up or accepted arguments
1114  *     is NULL, if the contracts_up and vres_down arguments are both NULL,
1115  *     or any of them has erroneous size or its elements are NULL or not in the
1116  *      valid range respectively
1117  **/
1118 int frsh_group_negotiate
1119    (const frsh_contracts_group_t *contracts_up,
1120     const frsh_vres_group_t   *vres_down,
1121     frsh_vres_group_t         *vres_up);
1122
1123
1124
1125 /**
1126  * frsh_group_change_mode_sync()
1127  *
1128  * An extension of frsh_negotiate_group() by adding the possibility of
1129  * specifying also group contract renegotiation and removal.
1130  *
1131  * NOTE:  This function will be implemented in a second phase after
1132  *        having fully implemented frsh_group_negotiate() in order to
1133  *        better grasp possible issues that the problems it may raise.
1134  *
1135  *        This is a draft of the specification, it is yet subject to
1136  *        change.
1137  *
1138  * This operation performs a global (re)negotiation of a group of
1139  * contracts in an atomic way.  Contracts can be added, canceled or
1140  * renegotiated.  Note that any of the groups can be empty.
1141  *
1142  * If the on-line admission test is enabled, FRSH analizes the
1143  * schedulability of the context that would  result in the new
1144  * contract situation with removed, changed and added contracts.
1145  *
1146  * A successful return code will mean that all contracts have been
1147  * accepted  and all required operations (creation, cancellation or
1148  * update of vres) have been carried out to reach the new running
1149  * context.
1150  *
1151  * If for any reason one of the contracts is not accepted a
1152  * corresponding error shall be returned and no changes will be made
1153  * to the previously running context.
1154  *
1155  * This call is a synchronous, potentially blocking operation.  It
1156  * returns when the system has rejected the contracts or accepted them
1157  * and made them effective.  There is also an asynchronous
1158  * (non-blocking) version of this function below.
1159  *
1160  * @param[in]  contracts_new_vres  Contracts to be added.
1161  * @param[out] vres_id_new  vres_id's corresponding to the new
1162  *                                    contracts.
1163  * @param[in]  contracts_update_vres New contracts for vres to
1164  *                                    be updated.
1165  * @param[in]  vres_update  vres_id's corresponding to the
1166  *                              contracts that have to be updated.
1167  * @param[in]  vres_removed Vres_id's to be removed.
1168  *
1169  * @return
1170  *    FRSH_ERR_BAD_ARGUMENT Invalid pointer or vres_id ranges.
1171  *    FRSH_ERR_CONTRACT_ID_ALREADY_EXISTS contract_id not unique.
1172  *    FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided
1173  *                                   vres_ids is not recognised.
1174  *    FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread
1175  *                           is not scheduled under FRSH.
1176  *    FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong
1177  *                           or not running.
1178  *    FRSH_ERR_INTERNAL_ERROR:  Erroneous binding or malfunction of
1179  *                           FRSH main scheduler.
1180  *    FRSH_ERR_REJECTED_CONTRACT:  The negotiation of one of the
1181  *                           proposed contracts has failed.
1182  *
1183  **/
1184 int frsh_group_change_mode_sync
1185     (const frsh_contracts_group_t *contracts_new_vres,
1186      frsh_vres_group_t *vres_id_new,
1187      const frsh_contracts_group_t *contracts_update_vres,
1188      const frsh_vres_group_t *vres_update,
1189      const frsh_vres_group_t *vres_removed);
1190
1191
1192 /**
1193  * frsh_group_change_mode_async()
1194  *
1195  * This operation enqueues a global renegotiation of a group of
1196  * contracts (with a possible addition of new vres) and returns
1197  * immediately.  The renegotiation is performed asynchronously as soon
1198  * as it is practical.
1199  *
1200  * NOTE:  This function will be implemented in a second phase after
1201  *        having fully implemented frsh_negotiate_group() in order to
1202  *        better grasp possible issues that the problem may raise.
1203  *
1204  *        This is a draft of the specification, it is yet subject to
1205  *        change.
1206  *
1207  * This is an asynchronous (non-blocking) version of
1208  * frsh_group_change_mode_sync().  Note however that there must
1209  * be at least one existing thread involved in the operation (to be
1210  * canceled or have its contract updated).  An operation of puring
1211  * adding a group of new contracts can only be done synchronously.
1212  *
1213  * The status of the operation (in progress, admitted or rejected) can
1214  * be queried via frsh_vres_get_renegotiation_status() invoked for any of
1215  * the vres involved in the renegotiation (updated or to be
1216  * removed).  As an option, a signal can be sent to the caller to
1217  * notify the end-result  of the operation.
1218  *
1219  * @param[in]  contracts_new_vres  Contracts for new vres to be
1220  *                                    added.
1221  * @param[in]  contract_ids Contract id's for the corresponding new
1222  *                          vres to be added.
1223  * @param[out] vres_id_new  vres_id's corresponding to the new
1224  *                                    contracts.
1225  * @param[in]  contracts_update_vres New contracts for vres to
1226  *                                    be updated.
1227  * @param[in]  vres_update  vres_id's corresponding to the
1228  *                              contracts that have to be updated.
1229  * @param[in]  vres_removed vres_id's to be removed.
1230  *
1231  * @param[in] sig_notify  Signal number where the coller expects to
1232  *                        receive the information.
1233  * @param[in] sig_value   Signal data associated with that signal.
1234  *
1235  * @return
1236  *    FRSH_ERR_BAD_ARGUMENT Invalid pointer or vres_id ranges.  Also
1237  *                          when the request is for adding only new contracts.
1238  *    FRSH_ERR_CONTRACT_ID_ALREADY_EXISTS contract_id not unique.
1239  *    FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided
1240  *                                   vres_id's is not recognised.
1241  *    FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread
1242  *                           is not scheduled under FRSH.
1243  *    FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong
1244  *                           or not running.
1245  *    FRSH_ERR_INTERNAL_ERROR:  Erroneous binding or malfunction of
1246  *                           FRSH main scheduler.
1247  *    FRSH_ERR_REJECTED_CONTRACT:  The negotiation of one of the
1248  *                           proposed contracts has failed.
1249  **/
1250 int frsh_group_change_mode_async
1251     (const frsh_contracts_group_t *contracts_new_vres,
1252      const frsh_contract_ids_group_t *contract_ids,
1253      frsh_vres_group_t *vres_id_new,
1254      const frsh_contracts_group_t *contracts_update_vres,
1255      const frsh_vres_group_t *vres_update,
1256      const frsh_vres_group_t *vres_removed,
1257      frsh_signal_t         signal_notify,
1258      frsh_signal_info_t    signal_info);
1259
1260 /*@}*/
1261
1262
1263
1264 ////////////////////////////////////////////////////
1265 //           OBTAINING INFORMATION FROM THE SCHEDULER
1266 ////////////////////////////////////////////////////
1267
1268 /**
1269  * @defgroup getschedinfo Obtaining information from the scheduler
1270  *
1271  * @ingroup core
1272  *
1273  * The following functions are used to obtain available budget and
1274  * resource usage in the system.  They can be used to adapt the
1275  * execution of threads according to the load of the system.
1276  *
1277  * @{
1278  **/
1279
1280
1281 /**
1282  * frsh_config_is_admission_test_enabled()
1283  *
1284  * Returns true if the system is
1285  * configured with the on-line admission test enabled, or false
1286  * otherwise.  This situation can only be changed at compile time.
1287  **/
1288 bool frsh_config_is_admission_test_enabled();
1289
1290 /**
1291  * frsh_vres_get_usage()
1292  *
1293  * This function stores the current execution time spent by the
1294  * threads bound to the specified vres in the variable pointed to by
1295  * cpu_time.
1296  *
1297  * @return 0 if successful
1298  *   FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
1299  *     cpu_time is NULL
1300  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
1301  *     scheduled under the FRSH
1302  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
1303  *   FRSH_ERR_NOT_CONTRACTED_VRESR : if the vres of the calling thread
1304  *     has been cancelled or it is not valid
1305  *
1306  **/
1307 int frsh_vres_get_usage
1308    (frsh_vres_id_t vres,
1309     struct timespec *spent);
1310
1311 /**
1312  * frsh_vres_get_remaining_budget()
1313  *
1314  * This function stores in the variable pointed to by budget the
1315  * remaining execution-time budget associated with the specified
1316  * vres.
1317  *
1318  *  @return 0 if successful
1319  *   FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
1320  *     budget is NULL
1321  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
1322  *     scheduled under the FRSH
1323  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
1324  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
1325  *     has been cancelled or it is not valid
1326  *
1327  **/
1328 int frsh_vres_get_remaining_budget
1329    (frsh_vres_id_t vres,
1330     struct timespec *budget);
1331
1332
1333 /**
1334  * frsh_vres_get_budget_and_period()
1335  *
1336  * This function stores in the variables
1337  * pointed to by budget and period, the execution-time budget and the
1338  * period respectively associated with the specified vres. If any of
1339  * these pointers is NULL, the corresponding information is not stored.
1340  *
1341  * @return 0 if successful
1342  *   FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range,
1343  *     or budget and period are both NULL
1344  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
1345  *     scheduled under the FRSH
1346  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
1347  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
1348  *     has been cancelled or it is not valid
1349  *
1350  **/
1351 int frsh_vres_get_budget_and_period
1352    (frsh_vres_id_t vres,
1353     struct timespec *budget,
1354     struct timespec *period);
1355
1356 /*@}*/
1357
1358 /////////////////////////////////////////////////////////////////////
1359 //           SERVICE THREAD TUNING
1360 /////////////////////////////////////////////////////////////////////
1361 /**
1362  * @defgroup servthtuning Service thread tuning
1363  *
1364  * @ingroup core
1365  *
1366  * The following functions are used to obtain available budget and
1367  * resource usage in the system.  They can be used to adapt the
1368  * execution of threads to the load of the system.
1369  *
1370  * @{
1371  **/
1372
1373 /**
1374  * frsh_service_thread_set_data()
1375  *
1376  * This function allows the application to change the period and
1377  * budget of the service thread that makes the
1378  * negotiations. Increasing the utilization of this thread makes the
1379  * negotiations faster, but introduces additional load in the system
1380  * that may decrease the bandwidth available for the vres. For this
1381  * call, the system will make a schedulability analysis to determine
1382  * if the new situation is acceptable or not. This is reported back in
1383  * the variable pointed to by accepted. If the new service thread data
1384  * is accepted, the system will reassign budgets and periods to the
1385  * vres according to the new bandwidth available, in the same way
1386  * as it does for a regular contract negotiation.
1387  *
1388  * When its budget is exhausted, the service thread may run in the
1389  * background
1390  *
1391  * The service thread starts with a default budget and period that are
1392  * configurable
1393  *
1394  * Implementation dependency: in the fixed priority implementtaion of
1395  * frsh, the default priority is lower than the priority of any vres,
1396  * but higher than the background. According to the
1397  * implementation-dependent module the priority is adjustable by means
1398  * of a function that changes its preemption level
1399  *
1400  * @return 0 if successful
1401  *   FRSH_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL or
1402  *     the budget value is greater than the period value
1403  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
1404  *     scheduled under the FRSH
1405  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
1406  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
1407  *     has been cancelled or it is not valid
1408  *
1409  **/
1410 int frsh_service_thread_set_data (const struct timespec *budget,
1411                                   const struct timespec *period,
1412                                   bool                  *accepted);
1413
1414 /**
1415  * frsh_service_thread_get_data()
1416  *
1417  * this function returns in the variables pointed by budget and
1418  * period, respectively, the current budget and period of the service
1419  * thread.
1420  *
1421  * @return 0 if successful
1422  *   FRSH_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL
1423  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
1424  *     scheduled under the FRSH
1425  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
1426  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
1427  *     has been cancelled or it is not valid
1428  *
1429  **/
1430 int frsh_service_thread_get_data
1431    (struct timespec *budget,
1432     struct timespec *period);
1433
1434
1435 /*@}*/
1436
1437
1438 ////////////////////////////////////////////////////////////////////////
1439 //           BACKGROUND MANAGEMENT
1440 ////////////////////////////////////////////////////////////////////////
1441
1442 //A round-robin background scheduling policy is available for those
1443 //threads that do not have real-time requirements. Because some of
1444 //these threads may require sharing information with other threads run
1445 //by regular vres.  Special background contracts may be created for
1446 //specifying the synchronization requirements.
1447
1448 //The way of specifying a background contract is by setting
1449 //contract_type to FRSH_CT_BACKGROUND. Negotiation may fail if the contract uses
1450 //shared_objects. If the contract has no shared_objects the returned
1451 //vres id represents the background and may be used to bind more
1452 //than one thread. If the contract has shared objects a vres is
1453 //created to keep track of them, but the associated threads are
1454 //executed in the background, together with the other background
1455 //threads
1456
1457
1458
1459
1460
1461 #endif // _FRSH_CORE_H_