include/fosa_app_def_sched.h

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