include/fosa_app_def_sched.h

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