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