frsh_shared_objects.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_shared_objects.h
  59
  60 //==============================================
  61 //  ******** *******    ********  **      **
  62 //  **///// /**////**  **//////  /**     /**
  63 //  **      /**   /** /**        /**     /**
  64 //  ******* /*******  /********* /**********
  65 //  **////  /**///**  ////////** /**//////**
  66 //  **      /**  //**        /** /**     /**
  67 //  **      /**   //** ********  /**     /**
  68 //  //       //     // ////////   //      //
  69 //
  70 // FRSH(FRescor ScHeduler), pronounced "fresh"
  71 //==============================================
  72
  73 #ifndef _FRSH_SHARED_OBJECTS_H_
  74 #define _FRSH_SHARED_OBJECTS_H_
  75
  76 #include "frsh_shared_objects_types.h"
  77 #include "frsh_core_types.h"
  78
  79 FRSH_CPP_BEGIN_DECLS
  80
  81 #define FRSH_SHAREDOBJS_MODULE_SUPPORTED       1
  82
  83 /**
  84  * @file frsh_shared_objects.h
  85  **/
  86
  87 /**
  88  * @defgroup sharedobj Shared Objects module
  89  *
  90  * This module includes the functions to declare and use shared
  91  * objects in different critical sections.
  92  *
  93  * A shared object is an abstraction of a mutex giving it a name and a
  94  * possible priority ceiling.
  95  *
  96  * A critical section represents a usage of a shared object with a wcet.
  97  * One or more critical sections can be included in a contract.
  98  *
  99  * There are two types of shared_objects: protected and unprotected.
 100  *
 101  * -  <b>UNPROTECTED shared objects</b>.  These shared objects are always
 102  *    used in trusted critical sections for which the worst-case
 103  *    execution times can be guaranteed not to be exceeded by the
 104  *    application designer (eg because tools have been used to verify
 105  *    the schedulability off-line).  Given these conditions, there is
 106  *    no need to have a mechanism to monitor their execution time, with
 107  *    the corresponding savings in overhead.
 108  *
 109  * -  <b>PROTECTED shared objects</b>.  For these shared objects a mechanism
 110  *    may be used in one or more of their critical sections to monitor
 111  *    and enforce their worst-case execution time.  These shared
 112  *    objects are restricted to data in regular memory because a
 113  *    mechanism to save and restore the state is necessary in order to
 114  *    cleanly abort a misbehaving critical section.\n
 115  *
 116  * Critical sections are categorized depending on wcet monitoring and
 117  * rollback capability.
 118  *
 119  * - <b>UNCHECKED critical sections</b>.  These critical sections are
 120  *   not monitored by FRSH for wcet compliance.  Their wcet value is
 121  *   used only for analysis purposes (calculation of blocking times).
 122  *
 123  * - <b>READ critical sections</b>.  These critical sections have
 124  *   their wcet enforced but they don't have any rollback action
 125  *   applied when their wcet is exceeded.
 126  *
 127  * - <b>WRITE critical sections</b>.  These critical sections have
 128  *   their wcet monitored and they have a rollback mechanism applied
 129  *   to their memory areas prior to being aborted for exceeding their
 130  *   declared wcet.
 131  *
 132  * READ and WRITE critical sections must use PROTECTED shared objects,
 133  * but UNCHECKED critical sections may use PROTECTED or UNPROTECTED
 134  * shared objects.
 135  *
 136  * The monitoring mechanism for READ and WRITE critical section works
 137  * by executing them indirectly via a registered callback function.
 138  * UNCHECKED critical sections are executed directly by the
 139  * application.
 140  *
 141  * The rollback mechanism for WRITE critical sections requires an
 142  * additional registration of the memory areas that the callback
 143  * function may modify.  With this data FRSH will do an initial saving
 144  * of this areas that will used for restoration when there is a rollback
 145  * operation.
 146  *
 147  * Note that extra time for the saving and the restoration must be
 148  * included in the wcet specified for a WRITE critical section.
 149  * Functions are provided to assist the developer in calculating this
 150  * extra time.
 151  *
 152  * The reason for allowing the use of PROTECTED shared objects in
 153  * UNCHECKED critical sections is to allow for legacy or trusted
 154  * code that would use UNCHECKED critical sections to share a shared
 155  * object with an untrusted code using READ or WRITE critical sections.
 156  *
 157  * This module makes use of the following constants defined in
 158  * frsh_configuration_parameters.h.  We list them with our proposed
 159  * default values.
 160  *
 161  *        FRSH_MAX_N_SHARED_OBJECTS 100 \n
 162  *        FRSH_MAX_N_CRITICAL_SECTIONS 20\n
 163  *        FRSH_MAX_N_MEMORY_AREAS 4\n
 164  *
 165  * @{
 166  **/
 167
 168
 169 /////////////////////////////////////////////////////
 170 //           SHARED OBJECTS & OPERATIONS MANAGEMENT
 171 /////////////////////////////////////////////////////
 172 /**
 173  * @defgroup so_opp_mgmnt Shared Objects & Operations
 174  * @ingroup sharedobj
 175  *
 176  * These functions are used to declare shared objects and link them
 177  * with a mutex.
 178  *
 179  * @{
 180  **/
 181
 182 /**
 183  * frsh_sharedobj_init()
 184  *
 185  * Initialization of shared objects. If the object identified by
 186  * obj_label does not yet exist, it is created, a handle to the object is
 187  * returned in the variable pointed to by obj_handle, and the
 188  * specified mutex is initialized with the appropriate attributes
 189  * necessary for the current implementation.  If the object already
 190  * exists, the function fails. The object is created according to the
 191  * kind of object (protected or unprotected) specified by obj_kind
 192  *
 193  * @param[in] obj_label  Label defined by the application.  Char * for
 194  *                       a string of FRSH_MAX_SIZE_SHARED_OBJ_LABEL
 195  *                       characters (+ null terminating \0).
 196  *
 197  * @param[in] obj_kind  Whether it is protected or unprotected.
 198  *
 199  * @param[out] obj_handle Placeholder for the shared object handle.
 200  *
 201  * @param[out] mutex  Placeholder for the mutex.
 202  *
 203  * @return 0 if no error \n
 204  *   FRSH_ERR_BAD_ARGUMENT : if obj_label, obj_handle, or mutex are NULL \n
 205  *   FRSH_ERR_SHARED_OBJ_ALREADY_INITIALIZED : if the object identified
 206  *      by label already exists \n
 207  *   FRSH_ERR_TOO_MANY_SHARED_OBJS : if the number of already
 208  *      initialized shared objects exceed the
 209  *      FRSH_MAX_N_SHARED_OBJECTS configuration parameter. \n
 210  *   .
 211  *   It may also return any of the error codes that are returned by
 212  *   fosa_mutex_init() and fosa_mutex_set_prioceiling().
 213  *
 214  **/
 215 int frsh_sharedobj_init
 216    (char      *obj_label,
 217     frsh_sharedobj_kind_t   obj_kind,
 218     frsh_sharedobj_handle_t *obj_handle,
 219     frsh_mutex_t          *mutex);
 220
 221
 222
 223 /**
 224  * frsh_sharedobj_get_handle()
 225  *
 226  * Getting the handle of shared objects. If the object already exists
 227  * a handle to the object is returned in the variable pointed to by
 228  * obj_handle. Otherwise, an error code is returned.
 229  *
 230  * @param[in] obj_label  Defined by the application at object creation
 231  *                time. Char * for a string of FRSH_MAX_SIZE_SHARED_OBJ_LABEL
 232  *                characters (+ null terminating \0).
 233  *
 234  * @param[out] obj_handle Placeholder for the object handle.
 235  *
 236  * @return 0 if no error \n
 237  *    FRSH_ERR_BAD_ARGUMENT : if label or obj_handle are NULL \n
 238  *    FRSH_ERR_SHARED_OBJ_NOT_INITIALIZED : if the shared object identified
 239  *        by obj_label does not exist \n
 240  *    FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 241  *      scheduled under FRSH \n
 242  *    FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 243  *      running \n
 244  *    FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 245  *      has been cancelled or it is not valid \n
 246  *   .
 247  *   It may also return any of the error codes that are returned by the
 248  *   fosa_mutex_init() function call
 249  *
 250  **/
 251 int frsh_sharedobj_get_handle
 252      (char *obj_label,
 253       frsh_sharedobj_handle_t *obj_handle);
 254
 255
 256 /**
 257  * frsh_sharedobj_get_mutex()
 258  *
 259  * Getting the mutex of shared objects.
 260  *
 261  * @param[in] obj_handle   Handle of the shared object
 262  *
 263  * @param[out] mutex  Placeholder for A POINTER to a pointer of the
 264  *                    mutex. We give the pointer to discourage the
 265  *                    application of using a local copy of the mutex.
 266  *
 267  * @return 0 if no error \n
 268  *   FRSH_ERR_BAD_ARGUMENT : if obj_handle or mutex are NULL or obj_handle
 269  *      is not correct or reference a wrong shared object \n
 270  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 271  *      scheduled under the FRSH \n
 272  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 273  *      running \n
 274  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 275  *      has been cancelled or it is not valid
 276  *
 277  **/
 278 int frsh_sharedobj_get_mutex
 279    (frsh_sharedobj_handle_t  obj_handle,
 280     frsh_mutex_t          **mutex);
 281
 282 /**
 283  * frsh_sharedobj_get_obj_kind()
 284  *
 285  * Get the object kind (protected/unprotected) of the object handle.
 286  *
 287  * @param[in] obj_handle   Handle of the shared object
 288  *
 289  * @param[out] obj_kind  Placeholder for an enumeration variable of
 290  *                       protected / unprotected.
 291  *
 292  * @return 0 if no error \n
 293  *   FRSH_ERR_BAD_ARGUMENT : if obj_handle or mutex are NULL or obj_handle
 294  *      is not correct or reference a wrong shared object \n
 295  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 296  *      scheduled under the FRSH \n
 297  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 298  *      running \n
 299  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 300  *      has been cancelled or it is not valid
 301  *
 302  **/
 303 int frsh_sharedobj_get_obj_kind
 304    (frsh_sharedobj_handle_t  obj_handle,
 305     frsh_sharedobj_kind_t   *obj_kind);
 306
 307 /**
 308  * frsh_sharedobj_remove()
 309  *
 310  * Allows the implementation to remove a shared object when the last
 311  * vres referencing it is cancelled. This removes the object id and
 312  * other internal data associated with the object, but does not remove
 313  * the mutex; this is done by the application through the common POSIX
 314  * API.
 315  *
 316  * @return 0 if no error \n
 317  *   FRSH_ERR_BAD_ARGUMENT : if obj_handle is NULL or obj_handle
 318  *      is not correct or references a wrong shared object \n
 319  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 320  *      scheduled under the FRSH \n
 321  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 322  *      running \n
 323  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 324  *      has been cancelled or it is not valid
 325  *
 326  **/
 327 int frsh_sharedobj_remove
 328    (frsh_sharedobj_handle_t  obj_handle);
 329
 330
 331
 332 /*@}*/
 333
 334 /////////////////////////////////////////////////////
 335 //                       CRITICAL SECTIONS
 336 /////////////////////////////////////////////////////
 337 /**
 338  * @defgroup so_critical Critical Sections
 339  * @ingroup sharedobj
 340  *
 341  * These functions are used to create and manage the parameters
 342  * of critical sections. Critical sections are operations that
 343  * make use of a shared object in a mutually exclusive way.
 344  *
 345  * @{
 346  **/
 347
 348 /**
 349  * frsh_csect_init()
 350  *
 351  * Initialize the critical section pointed to by csect
 352  * with a handle to its shared object, and the worst-case execution
 353  * time.
 354  *
 355  * The operation_kind is set to FRSH_CSOK_UNCHECKED.
 356  *
 357  * @param[in] obj_handle  Shared object previously initialised.
 358  *
 359  * @param[in] wcet Execution time of the critical section.  This
 360  *                 budget is consumed in parallel with the vres budget.
 361  *
 362  * @param[out] csect Critical section memory placeholder.
 363  *
 364  * @return 0 if no error \n
 365  *   FRSH_ERR_BAD_ARGUMENT : if obj_handle is NULL \b or \n
 366  *       obj_handle is not correct or references a wrong shared object \b or \n
 367  *       if wcet  is in the wrong format for specifying a time interval value \n
 368  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 369  *      scheduled under the FRSH \n
 370  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 371  *      running \n
 372  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 373  *      has been cancelled or it is not valid
 374  *
 375  **/
 376 int frsh_csect_init
 377     (frsh_sharedobj_handle_t obj_handle,
 378      frsh_rel_time_t wcet,
 379      frsh_csect_t *csect);
 380
 381
 382 /**
 383  * frsh_csect_get_sharedobj_handle()
 384  *
 385  * Get in the variable pointed to by obj_handle the handle to the
 386  * shared object stored in the critical section referenced by csect
 387  *
 388  * @return 0 if no error \n
 389  *   FRSH_ERR_BAD_ARGUMENT : if csect or obj_handle are NULL or csect
 390  *      is not correct \n
 391  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 392  *      scheduled under the FRSH \n
 393  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 394  *      running \n
 395  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 396  *      has been cancelled or it is not valid
 397  *
 398  **/
 399 int frsh_csect_get_sharedobj_handle
 400     (const frsh_csect_t *csect,
 401      frsh_sharedobj_handle_t * obj_handle);
 402
 403 /**
 404  * frsh_csect_get_wcet()
 405  *
 406  * Get in the variable pointed to by wcet the worst-case execution time
 407  * of the operation stored in the critical section referenced by csect.
 408  *
 409  * @return 0 if no error \n
 410  *   FRSH_ERR_BAD_ARGUMENT : if csect or wcet are NULL or csect
 411  *      is not correct \n
 412  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 413  *      scheduled under FRSH \n
 414  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 415  *      running \n
 416  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 417  *      has been cancelled or it is not valid
 418  *
 419  **/
 420 int frsh_csect_get_wcet
 421     (const frsh_csect_t *csect,
 422      frsh_rel_time_t *wcet);
 423
 424
 425 /**
 426  * frsh_csect_register_read_op()
 427  *
 428  * Register the given operation with the critical section and set
 429  * op_kind to FRSH_CSOK_READ.
 430  *
 431  * The function returns an error if the shared_object is unprotected.
 432  *
 433  * @return 0 if no error \n
 434  *   FRSH_ERR_BAD_ARGUMENT : if csect or op are NULL or if csect points
 435  *      to a wrong critical section or if the shared_object is of type
 436  *      unprotected.
 437  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 438  *      scheduled under FRSH \n
 439  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 440  *      running \n
 441  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 442  *      has been cancelled or it is not valid
 443  *
 444  **/
 445 int frsh_csect_register_read_op
 446     (frsh_csect_t *csect,
 447      frsh_csect_op_t op);
 448
 449 /**
 450  * frsh_csect_register_write_op()
 451  *
 452  * Register the given operation with the critical section, register
 453  * the memory areas and set op_kind to FRSH_CSOK_WRITE.
 454  *
 455  * If the memory areas are empty the functions returns an error.
 456  *
 457  * The function returns an error if the shared_object is unprotected.
 458  *
 459  * @return 0 if no error \n
 460  *   FRSH_ERR_BAD_ARGUMENT : if op, csect or areas are NULL or csect points
 461  *      to a wrong critical section, or areas has a wrong size, or if the
 462  *      shared_object of csect is of type unprotected.
 463  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 464  *      scheduled under the FRSH \n
 465  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 466  *      running \n
 467  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 468  *      has been cancelled or it is not valid
 469  *
 470  **/
 471 int frsh_csect_register_write_op
 472     (frsh_csect_t *csect,
 473      frsh_csect_op_t op,
 474      const frsh_memory_areas_t *areas);
 475
 476
 477 /**
 478  * frsh_csect_get_op_kind()
 479  *
 480  * Returns the type of operation (read/write/unchecked) of the critical section.
 481  *
 482  * @return 0 if no error \n
 483  *   FRSH_ERR_BAD_ARGUMENT : if csect or op_kind are NULL or csect
 484  *      is not correct \n
 485  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 486  *      scheduled under FRSH \n
 487  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 488  *      running \n
 489  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 490  *      has been cancelled or it is not valid
 491  *
 492  **/
 493 int frsh_csect_get_op_kind
 494     (const frsh_csect_t *csect,
 495      frsh_csect_op_kind_t *op_kind);
 496
 497
 498 /**
 499  * frsh_csect_get_read_op()
 500  *
 501  * Get into the variable pointed to by op the operation pointer stored
 502  * in the critical section referenced by csect.
 503  *
 504  * If the csect is of type write or unchecked it returns an error.
 505  *
 506  * @return 0 if no error \n
 507  *   FRSH_ERR_BAD_ARGUMENT : if csect is NULL or points to a wrong
 508  *      critical section, or to a critical section that is not of the
 509  *      FRSH_CSOK_READ kind \n
 510  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 511  *      scheduled under FRSH \n
 512  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 513  *      running \n
 514  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 515  *      has been cancelled or it is not valid
 516  *
 517  **/
 518 int frsh_csect_get_read_op
 519     (const frsh_csect_t *csect,
 520      frsh_csect_op_t *op);
 521
 522
 523
 524 /**
 525  * frsh_csect_get_write_op()
 526  *
 527  * Get the operation pointer and the memory areas stored in the csect.
 528  *
 529  * If the csect is of type read or unchecked.
 530  *
 531  * @return 0 if no error \n
 532  *   FRSH_ERR_BAD_ARGUMENT : if csect is NULL or points to a wrong
 533  *      critical section, or to a critical section that is not of the
 534  *      FRSH_CSOK_WRITE kind \n
 535  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 536  *      scheduled under FRSH \n
 537  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 538  *      running \n
 539  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 540  *      has been cancelled or it is not valid \n
 541  *
 542  **/
 543 int frsh_csect_get_write_op
 544     (const frsh_csect_t *csect,
 545      frsh_csect_op_t *op,
 546      frsh_memory_areas_t *areas);
 547
 548
 549 /**
 550  * frsh_csect_invoke()
 551  *
 552  * Invoke the registered operation in the critical section, with the pointers
 553  * to the input and output parameters specified by input_arg and
 554  * output arg.
 555  *
 556  * If the section is of type FRSH_CSOK_UNCHECKED, the function returns
 557  * an error.
 558  *
 559  * For read operations, the mutex is locked, the csect budget is set equal
 560  * to the wcet, the registered read operation is invoked, and then the
 561  * mutex is unlocked; if the csect budget expires, the operation is
 562  * interrupted, the mutex is unlocked, and the function returns with
 563  * an error code.
 564  *
 565  * For write operations, the mutex is locked, the registered memory
 566  * areas are backed up, the csect budget is set equal to the wcet, the
 567  * registered write operation is called, and the mutex is unlocked. If
 568  * the csect budget expires, the operation is interrupted, the backed-up
 569  * memory areas are recovered, the mutex is unlocked, and the function
 570  * returns with an error code. The blocking time suffered by higher
 571  * priority tasks is at most the wcet of the operation plus the backup
 572  * time plus the recovery time.
 573  *
 574  * If the shared object in the critical section is not protected it
 575  * returns an error.
 576  *
 577  * @return 0 if no error \n
 578  *   FRSH_ERR_BAD_ARGUMENT : if csect is NULL or points to a wrong
 579  *      critical section, or to a critical section that is unprotected \n
 580  *   FRSH_ERR_BUDGET_EXPIRED : the csect budget expired and the protected
 581  *      operation was interrupted \n
 582  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 583  *      scheduled under FRSH \n
 584  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 585  *      running \n
 586  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 587  *      has been cancelled or it is not valid
 588  *
 589  **/
 590 int frsh_csect_invoke
 591     (const frsh_csect_t *csect,
 592      const void * input_arg,
 593      void * output_arg);
 594
 595 /**
 596  * frsh_csect_get_blocking_time()
 597  *
 598  * Get in the variable pointed to by blocking the maximum blocking
 599  * time of the operation of the referenced protected critical section.
 600  *
 601  * For read or unchecked operations, the maximum blocking time is the wcet.
 602  *
 603  * For write operations, the maximum blocking time suffered by higher
 604  * priority tasks is the wcet of the operation plus the backup time
 605  * plus the recovery time.
 606  *
 607  * @return 0 if no error \n
 608  *   FRSH_ERR_BAD_ARGUMENT : if csect or blocking are NULL or if csect
 609  *      points to a wrong critical section, or to a critical section
 610  *      that is unprotected \n
 611  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 612  *      scheduled under FRSH \n
 613  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 614  *      running \n
 615  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
 616  *      has been cancelled or it is not valid
 617  *
 618  **/
 619 int frsh_csect_get_blocking_time
 620     (const frsh_csect_t *csect,
 621      frsh_rel_time_t *blocking);
 622
 623
 624 /**
 625  * frsh_csect_destroy()
 626  *
 627  * Destroy a critical section, deallocating all the resources that may
 628  * have been allocated to it.
 629  **/
 630 int frsh_csect_destroy
 631    (frsh_csect_t *csect);
 632
 633 /**
 634  * frsh_csect_register_thread()
 635  *
 636  * Register the calling thread for invoking time-protected critical
 637  * sections via frsh_csect_invoke.
 638  **/
 639 int frsh_csect_register_thread();
 640
 641 /**
 642  * frsh_csect_deregister_thread()
 643  *
 644  * Deregister the calling thread from being able to invoke
 645  * time-protected critical sections. This operation releases system
 646  * resources that may have been allocated for the thread.
 647  **/
 648 int frsh_csect_deregister_thread();
 649
 650
 651
 652 /*@}*/ /* For so_critical group */
 653
 654
 655 /////////////////////////////////////////////////////
 656 //                       CONTRACT PARAMETERS
 657 /////////////////////////////////////////////////////
 658 /**
 659  * @defgroup so_contract Shared Objects & Contract Parameters
 660  * @ingroup sharedobj
 661  *
 662  * These functions are used to link shared objects to contracts via
 663  * critical sections.
 664  *
 665  * @{
 666  **/
 667
 668
 669 /**
 670  * frsh_contract_set_csects()
 671  *
 672  * The operation updates the specified contract parameters object by
 673  * setting its critical sections to the specified input parameter.
 674  *
 675  * @return 0 if no error \n
 676  *    FRSH_ERR_BAD_ARGUMENT :  if any of the pointers is NULL or
 677  *    the size of the critical_sections structure is less than zero
 678  *    or greater than FRSH_MAX_N_CRITICAL_SECTIONS
 679  *
 680  **/
 681 int frsh_contract_set_csects
 682   (frsh_contract_t     *contract,
 683    const frsh_csects_group_t *critical_sections);
 684
 685 /**
 686  * frsh_contract_get_csects()
 687  *
 688  * The operation obtains from the specified contract parameters object
 689  * its critical sections, and copies them to the places pointed to by
 690  * the specified input parameter.  Only those critical_section_data
 691  * records that are in use in the critical_sections structure are
 692  * copied (according to its size field).
 693  *
 694  * @return 0 if no error \n
 695  *    FRSH_ERR_BAD_ARGUMENT :  if any of the pointers is NULL
 696  *
 697  **/
 698 int frsh_contract_get_csects
 699       (const frsh_contract_t *contract,
 700        frsh_csects_group_t    *critical_sections);
 701
 702 /*@}*/ /* For so_contract group */
 703
 704 /*@}*/ /* For shared_objects group */
 705
 706 FRSH_CPP_END_DECLS
 707
 708 #endif // _FRSH_SHARED_OBJECTS_H_