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