include/fosa_app_def_sched.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. Politecnica  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 //  This file is part of the FRSH implementation
  24 //
  25 //  FRSH is free software; you can  redistribute it and/or  modify
  26 //  it under the terms of  the GNU General Public License as published by
  27 //  the Free Software Foundation;  either  version 2, or (at  your option)
  28 //  any later version.
  29 //
  30 //  FRSH  is distributed  in  the hope  that  it  will  be useful,  but
  31 //  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  32 //  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  33 //  General Public License for more details.
  34 //
  35 //  You should have  received a  copy of  the  GNU  General Public License
  36 //  distributed  with  FRSH;  see file COPYING.   If not,  write to the
  37 //  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  38 //  02111-1307, USA.
  39 //
  40 //  As a special exception, if you include this header file into source
  41 //  files to be compiled, this header file does not by itself cause
  42 //  the resulting executable to be covered by the GNU General Public
  43 //  License.  This exception does not however invalidate any other
  44 //  reasons why the executable file might be covered by the GNU General
  45 //  Public License.
  46 // -----------------------------------------------------------------------
  47 //fosa_app_def_sched.h
  48 //==============================================
  49 //  ********  ******    ********  **********
  50 //  **///// /**    **  **//////  /**     /**
  51 //  **      /**    ** /**        /**     /**
  52 //  ******* /**    ** /********* /**********
  53 //  **////  /**    ** ////////** /**//////**
  54 //  **      /**    **        /** /**     /**
  55 //  **      /**    **  ********  /**     /**
  56 //  //       /******/  ////////   //      //
  57 //
  58 // FOSA(Frescor Operating System Adaptation layer)
  59 //================================================
  60
  61
  62 #ifndef         FOSA_APP_DEF_SCHED_H_
  63 #define         FOSA_APP_DEF_SCHED_H_
  64
  65 /**
  66  * @defgroup appdefsched Application Defined Scheduling
  67  *
  68  * This module defines the function and types for an abstraction of
  69  * the Application Defined Scheduling.
  70  *
  71  * @{
  72  **/
  73
  74
  75
  76 /********************************
  77  * Application-defined scheduling
  78  ********************************/
  79
  80 /**
  81  * We make the following ASSUMPTIONS:
  82  *
  83  * - The ADS always executes in the user memory space, so we don't
  84  *   need to manage the memory space translation.
  85  *
  86  * - Only one application scheduler exists, so we don't need an
  87  *   scheduler_id.
  88  **/
  89
  90 /**
  91  * fosa_ads_scheduler_create()
  92  *
  93  * Create the application defined scheduler
  94  *
  95  * The application defined scheduler is created with the primitive
  96  * operations specified in the object pointed to by scheduler_ops.
  97  *
  98  * The clock used to read the time immediately before the invocation
  99  * of each primitive operation, to be reported to the scheduler via
 100  * the current_time parameter of each primitive operation is the
 101  * FOSA_CLOCK_REALTIME clock.
 102  *
 103  * The scheduler_data_size parameter is used to request that a memory
 104  * area of this size must be created and reserved for the scheduler to
 105  * store its state. A pointer to this area is passed to the scheduler
 106  * operations in the sched_data parameter.
 107  *
 108  * Parameter init_arg points to an area that contains configuration
 109  * information for the scheduler. The function creates a memory area
 110  * of init_arg_size bytes and copies into it the area pointed by
 111  * arg. A pointer to this new created area will be passed to the
 112  * primitive operation init() in its arg parameter.
 113  *
 114  * Returns 0 if successful; otherwise it returns an error code:
 115  *     EINVAL: The value of scheduler_ops was invalid
 116  *     EAGAIN: The system lacks enough resources to create the scheduler
 117  *
 118  * Alternatively, in case of error the implementation is allowed to
 119  * notify it to the system console and then terminate the FRSH
 120  * implementation and dependant applications
 121  **/
 122 int fosa_ads_scheduler_create
 123      (const fosa_ads_scheduler_ops_t * scheduler_ops,
 124       size_t scheduler_data_size,
 125       void * init_args,
 126       size_t init_args_size);
 127
 128 /**
 129  * fosa_thread_attr_setappscheduled()
 130  *
 131  * Set the appscheduled attribute of a thread attributes object
 132  *
 133  * This function is used to set the appscheduled attribute in the
 134  * object pointed to by attr. This attribute controls the kind of
 135  * scheduling used for threads created with it. If true, the thread is
 136  * scheduled by the application scheduler. If not, it is scheduled by
 137  * the system under a fixed priority scheduler
 138  *
 139  * Returns 0 if successful; otherwise it returns an error code:
 140  *     EINVAL: The value of attr is invalid
 141  *
 142  * Alternatively, in case of error the implementation is allowed to
 143  * notify it to the system console and then terminate the FRSH
 144  * implementation and dependant applications
 145  **/
 146 int fosa_thread_attr_setappscheduled
 147         (frsh_thread_attr_t *attr,
 148          bool appscheduled);
 149
 150 /**
 151  * fosa_thread_attr_getappscheduled()
 152  *
 153  * Get the appscheduled attribute of a thread attributes object
 154  *
 155  * This function is used to get the appscheduled attribute in the
 156  * object pointed to by attr. This attribute controls the kind of
 157  * scheduling used for threads created with it. If true, the thread is
 158  * scheduled by the application scheduler. If not, it is scheduled by
 159  * the system under a fixed priority scheduler.
 160  *
 161  * Returns 0 if successful; otherwise it returns an error code:
 162  *    EINVAL: The value of attr is invalid
 163  *
 164  * Alternatively, in case of error the implementation is allowed to
 165  * notify it to the system console and then terminate the FRSH
 166  * implementation and dependant applications
 167  **/
 168 int fosa_thread_attr_getappscheduled
 169         (const frsh_thread_attr_t *attr,
 170          bool *appscheduled);
 171
 172 /**
 173  * fosa_thread_attr_setappschedparam()
 174  *
 175  * Set the appsched_param attribute of a thread attributes object
 176  *
 177  * This function is used to set the appsched_param attribute in the
 178  * object pointed to by attr.  For those threads with appscheduled set
 179  * to true, this attribute represents the application-specific
 180  * scheduling parameters. If successful, the function shall set the
 181  * size of the appsched_param attribute to the value specified by
 182  * paramsize, and shall copy the scheduling parameters occupying
 183  * paramsize bytes and pointed to by param into that attribute
 184  *
 185  * Returns 0 if successful; otherwise it returns an error code:
 186  *    EINVAL: The value of attr is invalid, or paramsize is less than
 187  *            zero or larger than FOSA_ADS_SCHEDPARAM_MAX
 188  *
 189  * Alternatively, in case of error the implementation is allowed to
 190  * notify it to the system console and then terminate the FRSH
 191  * implementation and dependant applications
 192  **/
 193 int fosa_thread_attr_setappschedparam
 194         (frsh_thread_attr_t *attr,
 195          const void *param,
 196          size_t paramsize);
 197
 198 /**
 199  * fosa_thread_attr_getappschedparam()
 200  *
 201  * Get the appsched_param attribute of a thread attributes object
 202  *
 203  * This function is used to get the appsched_param attribute from the
 204  * object pointed to by attr.  For those threads with appscheduled set
 205  * to true, this attribute represents the application-specific
 206  * scheduling parameters. If successful, the function shall set the
 207  * value pointed to by paramsize to the size of the appsched_param
 208  * attribute, and shall copy the scheduling parameters occupying
 209  * paramsize bytes into the variable pointed to by param. This
 210  * variable should be capable of storing a number of bytes equal to
 211  * paramsize.
 212  *
 213  * Returns 0 if successful; otherwise it returns an error code:
 214  *     EINVAL: The value of attr is invalid
 215  *
 216  * Alternatively, in case of error the implementation is allowed to
 217  * notify it to the system console and then terminate the FRSH
 218  * implementation and dependant applications
 219  **/
 220 int fosa_thread_attr_getappschedparam
 221         (const frsh_thread_attr_t *attr,
 222          void *param,
 223          size_t *paramsize);
 224
 225 /**
 226  * fosa_ads_setappscheduled()
 227  *
 228  * Dynamically set the appscheduled attribute of a thread
 229  *
 230  * This function is used to dynamically set the appscheduled attribute
 231  * of the thread identified by thread. This attribute controls the
 232  * kind of scheduling used for threads created with it. If true, the
 233  * thread is scheduled by the application scheduler. If not, it is
 234  * scheduled by the system under a fixed priority scheduler.
 235  *
 236  * Returns 0 if successful; otherwise it returns an error code:
 237  *     EINVAL: The value of thread is invalid
 238  *
 239  *     EREJECT: the attachment of the thread to the frsh schehduler
 240  *     was rejected by the frsh scheduler possibly because of
 241  *     incorrect attributes, or because the requested minimum
 242  *     capacity cannot be guaranteed
 243  *
 244  * Alternatively, in case of error the implementation is allowed to
 245  * notify it to the system console and then terminate the FRSH
 246  * implementation and dependant applications
 247  **/
 248 int fosa_ads_setappscheduled
 249         (frsh_thread_id_t thread,
 250          bool appscheduled);
 251
 252 /**
 253  * fosa_ads_getappscheduled()
 254  *
 255  * Dynamically get the appscheduled attribute of a thread
 256  *
 257  * This function is used to dynamically get the appscheduled attribute
 258  * of the thread identified by thread. This attribute controls the
 259  * kind of scheduling used for threads created with it. If true, the
 260  * thread is scheduled by the application scheduler. If not, it is
 261  * scheduled by the system under a fixed priority scheduler
 262  *
 263  * Returns 0 if successful; otherwise it returns an error code:
 264  *     EINVAL: The value of thread is invalid
 265  *
 266  * Alternatively, in case of error the implementation is allowed to
 267  * notify it to the system console and then terminate the FRSH
 268  * implementation and dependant applications
 269  **/
 270 int fosa_ads_getappscheduled
 271         (frsh_thread_id_t thread,
 272          bool *appscheduled);
 273
 274
 275 /**
 276  * fosa_ads_setappschedparam()
 277  *
 278  * Dynamically set the appsched_param attribute of a thread
 279  *
 280  * This function is used to dynamically set the appsched_param
 281  * attribute of the thread identified by thread.  For those threads
 282  * with appscheduled set to true, this attribute represents the
 283  * application-specific scheduling parameters. If successful, the
 284  * function shall set the size of the appsched_param attribute to the
 285  * value specified by paramsize, and shall copy the scheduling
 286  * parameters occupying paramsize bytes and pointed to by param into
 287  * that attribute
 288  *
 289  * Returns 0 if successful; otherwise it returns an error code:
 290  *    EINVAL: The value of thread is invalid, or paramsize is less than
 291  *            zero or larger than FOSA_ADS_SCHEDPARAM_MAX
 292  *
 293  * Alternatively, in case of error the implementation is allowed to
 294  * notify it to the system console and then terminate the FRSH
 295  * implementation and dependant applications
 296  **/
 297 int fosa_ads_setappschedparam
 298         (frsh_thread_id_t thread,
 299          const void *param,
 300          size_t paramsize);
 301
 302 /**
 303  * fosa_ads_getappschedparam()
 304  *
 305  * Dynamically get the appsched_param attribute of a thread
 306  *
 307  * This function is used to dynamically get the appsched_param
 308  * attribute of the thread identified by thread.  For those threads
 309  * with appscheduled set to true, this attribute represents the
 310  * application-specific scheduling parameters. If successful, the
 311  * function shall set the variable pointed to by paramsize to the size
 312  * of the appsched_param attribute, and shall copy the scheduling
 313  * parameters occupying paramsize bytes into the variable pointed to
 314  * by param. This variable should be capable of storing a number of
 315  * bytes equal to paramsize.
 316  *
 317  *  Returns 0 if successful; otherwise it returns an error code:
 318  *     EINVAL: The value of thread is invalid, or paramsize is less than
 319  *             zero or larger than FOSA_ADS_SCHEDPARAM_MAX
 320  *
 321  * Alternatively, in case of error the implementation is allowed to
 322  * notify it to the system console and then terminate the FRSH
 323  * implementation and dependant applications.
 324  **/
 325 int fosa_ads_getappschedparam
 326         (frsh_thread_id_t thread,
 327          void *param,
 328          size_t *paramsize);
 329
 330
 331 /*********************************
 332  * ADS actions
 333  *
 334  * A scheduling actions object is used to specify a series of actions
 335  * to be performed by the system at the end of a scheduler primitive
 336  * operation. The order of the actions added to the object shall be
 337  * preserved.
 338  *
 339  *********************************/
 340
 341 /**
 342  * fosa_adsactions_addreject()
 343  *
 344  * Add a reject-thread action
 345  *
 346  * This function adds a thread-reject action to the object referenced
 347  * by sched_actions, that will serve to notify that the thread
 348  * identified by thread has not been accepted by the scheduler to be
 349  * scheduled by it, possibly because the thread contained invalid
 350  * application scheduling attributes, or because there are not enough
 351  * resources for the new thread.  At the end of the new_thread()
 352  * scheduler primitive operation, the parent of the rejected thread
 353  * waiting on a fosa_thread_create() or the rejected thread itself
 354  * waiting on a fosa_ads_setappscheduled() function shall complete the
 355  * function with an error code of EREJECT. If no reject-thread action
 356  * is added during the new_thread() scheduler primitive operation, the
 357  * thread is accepted to be scheduled by the scheduler and the
 358  * associated fosa_thread_create() or the fosa_ads_setappscheduled()
 359  * function shall be completed without error. For the function to
 360  * succeed, it has to be called from the new_thread() primitive
 361  * operation and for the thread that is requesting attachment to the
 362  * scheduler.
 363  *
 364  *  Returns 0 if successful; otherwise it returns an error code:
 365  *     ENOMEM: There is insufficient memory to add this action
 366  *     EPOLICY: The thread specified by thread is not the one requesting
 367  *               attachment to the scheduler, or the function is not being
 368  *               called from the new_thread primitive operation
 369  *     EINVAL: The value specified by sched_actions is invalid
 370  *
 371  * Alternatively, in case of error the implementation is allowed to
 372  * notify it to the system console and then terminate the FRSH
 373  * implementation and dependant applications
 374  **/
 375 int fosa_adsactions_add_reject(
 376         fosa_ads_actions_t *sched_actions,
 377         frsh_thread_id_t thread);
 378
 379 /**
 380  * fosa_adsactions_add_activate()
 381  *
 382  * Add a thread-activate action
 383  *
 384  * This function adds a thread-activate action to the object
 385  * referenced by sched_actions. In case the thread had been previously
 386  * suspended via posix_appsched_actions_addsuspend(), it will be
 387  * activated at the end of the primitive operation.
 388  *
 389  * In those implementations that do not support urgency scheduling,
 390  * the urgencu value is ignored. These implementations cannot support
 391  * the frsh hierarchical scheduling module.
 392  *
 393  * In those implementations supporting urgency-scheduling, the action
 394  * will cause the change of the urgency of the thread to the value
 395  * specified in the urgency argument. Besides, if the thread was
 396  * already active at the time the thread-activate action is executed,
 397  * the change or urgency will imply a reordering of the thread in its
 398  * priority queue, so that for threads of the same priority, those
 399  * with more urgency will be scheduled before those of less urgency.
 400  *
 401  * Returns 0 if successful; otherwise it returns an error code:
 402  *     ENOMEM: There is insufficient memory to add this action
 403  *     EPOLICY: The thread specified by thread has its appscheduled
 404  *              attribute set to false,
 405  *     EINVAL: The value specified by sched_actions is invalid
 406  *
 407  * Alternatively, in case of error the implementation is allowed to
 408  * notify it to the system console and then terminate the FRSH
 409  * implementation and dependant applications
 410  **/
 411 int fosa_adsactions_add_activate(
 412         fosa_ads_actions_t *sched_actions,
 413         frsh_thread_id_t thread,
 414         fosa_ads_urgency_t urgency);
 415
 416 /**
 417  * fosa_adsactions_add_suspend()
 418  *
 419  * Add a thread-suspend action
 420  *
 421  * This function adds a thread-suspend action to the object referenced
 422  * by sched_actions, that will cause the thread identified by thread
 423  * to be suspended waiting for a thread-activate action at the end of
 424  * the scheduler operation. If the thread was already waiting for a
 425  * thread-activate action the thread-suspend action has no effect. It
 426  * is an error trying to suspend a thread that is blocked by the
 427  * operating system.
 428  *
 429  *  Returns 0 if successful; otherwise it returns an error code:
 430  *     ENOMEM: There is insufficient memory to add this action
 431  *     EPOLICY: The thread specified by thread has its appscheduled
 432  *              attribute set to false,
 433  *     EINVAL: The value specified by sched_actions is invalid
 434  *
 435  *  Alternatively, in case of error the implementation is allowed to
 436  *  notify it to the system console and then terminate the FRSH
 437  *  implementation and dependant applications
 438  **/
 439 int fosa_adsactions_add_suspend(
 440         fosa_ads_actions_t *sched_actions,
 441         frsh_thread_id_t thread);
 442
 443 /**
 444  * fosa_adsactions_add_timeout()
 445  *
 446  * Add a timeout action
 447  *
 448  * This function adds a timeout action to the object referenced by
 449  * sched_actions, that will cause the timeout() scheduler operation to
 450  * be invoked if no other scheduler operation is invoked before
 451  * timeout expires. The timeout shall expire when the clock specified by
 452  * clock_id reaches the absolute time specified by the at_time
 453  * argument.
 454  *
 455  *  Returns 0 if successful; otherwise it returns an error code:
 456  *     ENOMEM: There is insufficient memory to add this action
 457  *     EPOLICY: The thread specified by thread has its appscheduled
 458  *              attribute set to false,
 459  *     EINVAL: The value specified by sched_actions is invalid
 460  *
 461  * Alternatively, in case of error the implementation is allowed to
 462  * notify it to the system console and then terminate the FRSH
 463  * implementation and dependant applications
 464  **/
 465 int fosa_adsactions_add_timeout(
 466         fosa_ads_actions_t *sched_actions,
 467         fosa_clock_id_t clock_id,
 468         const struct timespec *at_time);
 469
 470 /**
 471  * fosa_adsactions_add_thread_notification()
 472  *
 473  * Add a timed-thread-notification action
 474  *
 475  * This function adds a thread-notification action associated with the
 476  * thread specified in the thread argument that will cause the
 477  * notification_for_thread() scheduler operation to be invoked at the
 478  * time specified by at_time. This operation shall be invoked when the
 479  * clock specified by clock_id reaches the absolute time specified by
 480  * the at_time argument. In particular, a cpu-time clock may be used
 481  * for parameter clock_id.Only one thread-notification can be active
 482  * for each thread and clock. Calling the function shall remove the
 483  * former thread-notification, if any, that had been programmed for
 484  * the same thread and clock. A value of NULL for parameter at_time is
 485  * used to cancel a previous thread-notification, if any, for the
 486  * thread specified by thread and the clock specified by clock_id.
 487  *
 488  *  Returns 0 if successful; otherwise it returns an error code:
 489  *     ENOMEM: There is insufficient memory to add this action
 490  *     EPOLICY: The thread specified by thread has its appscheduled
 491  *              attribute set to false,
 492  *     EINVAL: The value specified by sched_actions is invalid
 493  *
 494  *  Alternatively, in case of error the implementation is allowed to
 495  *  notify it to the system console and then terminate the FRSH
 496  *  implementation and dependant applications
 497  **/
 498 int fosa_adsactions_add_thread_notification(
 499         fosa_ads_actions_t *sched_actions,
 500         frsh_thread_id_t thread,
 501         fosa_clock_id_t clock_id,
 502         const struct timespec *at_time);
 503
 504
 505 /**
 506  * fosa_ads_set_handled_signal_set()
 507  *
 508  * Specifiy the set of signals that will be handled by the application
 509  * scheduler
 510  *
 511  * This function is used to dynamically set the set of signals that
 512  * are handled by the application scheduler.  When a signal included
 513  * in this set is generated, the signal() primitive operation of the
 514  * application scheduler shall be executed. When a signal in tis set
 515  * is generated, it shall always imply the execution of the signal()
 516  * primitive operation, regardless of whether that signal could be
 517  * accepted by some other thread. Once the signal() primitive
 518  * operation is executed the signal is consumed, so no signal handlers
 519  * shall be executed and no threads using a sigwait operation shall
 520  * return for that particular signal instance.  For this function to
 521  * succeed, it has to be called from a primitive operation of a
 522  * scheduler.
 523  *
 524  * Returns 0 if successful; otherwise it returns an error code:
 525  *    EPOLICY: The function has not been called from a scheduler
 526  *              primitive operation
 527  *    EINVAL: The value specified by set is invalid
 528  *
 529  * Alternatively, in case of error the implementation is allowed to
 530  * notify it to the system console and then terminate the FRSH
 531  * implementation and dependant applications
 532  **/
 533 int fosa_ads_set_handled_signal_set(frsh_signal_t set[]);
 534
 535
 536 /**
 537  * fosa_ads_invoke_withdata()
 538  *
 539  * Explicitly invoke the scheduler, with data
 540  *
 541  * This function can be used by any thread in the process to invoke
 542  * the ads scheduler or to share data with it.
 543  *
 544  * If successful, the function shall cause the execution of the
 545  * primitive operation explicit_call_with_data() of the ads scheduler
 546  * with its thread parameter equal to the thread ID of the calling
 547  * thread, and its msg_size parameter equal to msg_size. In addition,
 548  * if msg_size is larger than zero, the function shall make available
 549  * to the scheduler a memory area whose contents are identical to the
 550  * memory area pointed to by msg in the msg parameter of the
 551  * explicit_call_with_data() primitive operation (note that copying
 552  * the information is not needed).
 553  *
 554  * The function shall not return until the system has finished
 555  * execution of the explicit_call_with_data() primitive operation. If
 556  * the reply argument is non NULL, the memory area pointed to by the
 557  * reply parameter of explicit_call_with_data() primitive operation is
 558  * copied into the memory area pointed to by reply, and its size is
 559  * copied into the variable pointed to by reply_size. The size of the
 560  * reply information is limited to the value FOSA_ADS_SCHEDINFO_MAX.
 561  *
 562  * The function shall fail if the size specified by msg_size is larger
 563  * than FOSA_ADS_SCHEDINFO_MAX.  The function shall fail if primitive
 564  * operation explicit_call_with_data() is set to NULL for the ads
 565  * scheduler.
 566  *
 567  *  Returns 0 if successful; otherwise it returns an error code:
 568  *     EPOLICY: The function been called from inside a scheduler
 569  *              primitive operation
 570  *     EINVAL: The value of msg_size is less than zero or larger than
 571  *             FOSA_ADS_SCHEDINFO_MAX
 572  *     EMASKED: The operation cannot be executed because the primitive
 573  *              operation explicit_call_with_data() is set to NULL
 574  *
 575  *  Alternatively, in case of error the implementation is allowed to
 576  *  notify it to the system console and then terminate the FRSH
 577  *  implementation and dependant applications
 578  **/
 579 int fosa_ads_invoke_withdata
 580    (const void *msg, size_t msg_size, void *reply, size_t *reply_size);
 581
 582 /*}*/
 583
 584
 585 #endif      /* !FOSA_APP_DEF_SCHED_H_ */