+// -----------------------------------------------------------------------
+// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+//
+// Universidad de Cantabria, SPAIN
+// University of York, UK
+// Scuola Superiore Sant'Anna, ITALY
+// Kaiserslautern University, GERMANY
+// Univ. Politecnica Valencia, SPAIN
+// Czech Technical University in Prague, CZECH REPUBLIC
+// ENEA SWEDEN
+// Thales Communication S.A. FRANCE
+// Visual Tools S.A. SPAIN
+// Rapita Systems Ltd UK
+// Evidence ITALY
+//
+// See http://www.frescor.org for a link to partners' websites
+//
+// FRESCOR project (FP6/2005/IST/5-034026) is funded
+// in part by the European Union Sixth Framework Programme
+// The European Union is not liable of any use that may be
+// made of this code.
+//
+// This file is part of the FRSH implementation
+//
+// FRSH is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2, or (at your option)
+// any later version.
+//
+// FRSH is distributed in the hope that it will be useful, but
+// WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// distributed with FRSH; see file COPYING. If not, write to the
+// Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
+// 02111-1307, USA.
+//
+// As a special exception, if you include this header file into source
+// files to be compiled, this header file does not by itself cause
+// the resulting executable to be covered by the GNU General Public
+// License. This exception does not however invalidate any other
+// reasons why the executable file might be covered by the GNU General
+// Public License.
+// -----------------------------------------------------------------------
+//fosa_app_def_sched.h
+//==============================================
+// ******** ****** ******** **********
+// **///// /** ** **////// /** /**
+// ** /** ** /** /** /**
+// ******* /** ** /********* /**********
+// **//// /** ** ////////** /**//////**
+// ** /** ** /** /** /**
+// ** /** ** ******** /** /**
+// // /******/ //////// // //
+//
+// FOSA(Frescor Operating System Adaptation layer)
+//================================================
+
+
+#ifndef FOSA_APP_DEF_SCHED_H_
+#define FOSA_APP_DEF_SCHED_H_
+
+/**
+ * @defgroup appdefsched Application Defined Scheduling
+ * @ingroup fosa
+ *
+ * This module defines the function and types for an abstraction of
+ * the Application Defined Scheduling.
+ *
+ * @{
+ **/
+
+
+
+/********************************
+ * Application-defined scheduling
+ ********************************/
+
+/**
+ * We make the following ASSUMPTIONS:
+ *
+ * - The ADS always executes in the user memory space, so we don't
+ * need to manage the memory space translation.
+ *
+ * - Only one application scheduler exists, so we don't need an
+ * scheduler_id.
+ **/
+
+/**
+ * fosa_ads_scheduler_create()
+ *
+ * Create the application defined scheduler
+ *
+ * The application defined scheduler is created with the primitive
+ * operations specified in the object pointed to by scheduler_ops.
+ *
+ * The clock used to read the time immediately before the invocation
+ * of each primitive operation, to be reported to the scheduler via
+ * the current_time parameter of each primitive operation is the
+ * FOSA_CLOCK_REALTIME clock.
+ *
+ * The scheduler_data_size parameter is used to request that a memory
+ * area of this size must be created and reserved for the scheduler to
+ * store its state. A pointer to this area is passed to the scheduler
+ * operations in the sched_data parameter.
+ *
+ * Parameter init_arg points to an area that contains configuration
+ * information for the scheduler. The function creates a memory area
+ * of init_arg_size bytes and copies into it the area pointed by
+ * arg. A pointer to this new created area will be passed to the
+ * primitive operation init() in its arg parameter.
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * EINVAL: The value of scheduler_ops was invalid
+ * EAGAIN: The system lacks enough resources to create the scheduler
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_ads_scheduler_create
+ (const fosa_ads_scheduler_ops_t * scheduler_ops,
+ size_t scheduler_data_size,
+ void * init_args,
+ size_t init_args_size);
+
+/**
+ * fosa_thread_attr_set_appscheduled()
+ *
+ * Set the appscheduled attribute of a thread attributes object
+ *
+ * This function is used to set the appscheduled attribute in the
+ * object pointed to by attr. This attribute controls the kind of
+ * scheduling used for threads created with it. If true, the thread is
+ * scheduled by the application scheduler. If not, it is scheduled by
+ * the system under a fixed priority scheduler
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * EINVAL: The value of attr is invalid
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_thread_attr_set_appscheduled
+ (frsh_thread_attr_t *attr,
+ bool appscheduled);
+
+/**
+ * fosa_thread_attr_get_appscheduled()
+ *
+ * Get the appscheduled attribute of a thread attributes object
+ *
+ * This function is used to get the appscheduled attribute in the
+ * object pointed to by attr. This attribute controls the kind of
+ * scheduling used for threads created with it. If true, the thread is
+ * scheduled by the application scheduler. If not, it is scheduled by
+ * the system under a fixed priority scheduler.
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * EINVAL: The value of attr is invalid
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_thread_attr_get_appscheduled
+ (const frsh_thread_attr_t *attr,
+ bool *appscheduled);
+
+/**
+ * fosa_thread_attr_set_appsched_params()
+ *
+ * Set the appsched_param attribute of a thread attributes object
+ *
+ * This function is used to set the appsched_param attribute in the
+ * object pointed to by attr. For those threads with appscheduled set
+ * to true, this attribute represents the application-specific
+ * scheduling parameters. If successful, the function shall set the
+ * size of the appsched_param attribute to the value specified by
+ * paramsize, and shall copy the scheduling parameters occupying
+ * paramsize bytes and pointed to by param into that attribute
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * EINVAL: The value of attr is invalid, or paramsize is less than
+ * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_thread_attr_set_appsched_params
+ (frsh_thread_attr_t *attr,
+ const void *param,
+ size_t paramsize);
+
+/**
+ * fosa_thread_attr_get_appsched_params()
+ *
+ * Get the appsched_param attribute of a thread attributes object
+ *
+ * This function is used to get the appsched_param attribute from the
+ * object pointed to by attr. For those threads with appscheduled set
+ * to true, this attribute represents the application-specific
+ * scheduling parameters. If successful, the function shall set the
+ * value pointed to by paramsize to the size of the appsched_param
+ * attribute, and shall copy the scheduling parameters occupying
+ * paramsize bytes into the variable pointed to by param. This
+ * variable should be capable of storing a number of bytes equal to
+ * paramsize.
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * EINVAL: The value of attr is invalid
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_thread_attr_get_appsched_params
+ (const frsh_thread_attr_t *attr,
+ void *param,
+ size_t *paramsize);
+
+/**
+ * fosa_ads_set_appscheduled()
+ *
+ * Dynamically set the appscheduled attribute of a thread
+ *
+ * This function is used to dynamically set the appscheduled attribute
+ * of the thread identified by thread. This attribute controls the
+ * kind of scheduling used for threads created with it. If true, the
+ * thread is scheduled by the application scheduler. If not, it is
+ * scheduled by the system under a fixed priority scheduler.
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * EINVAL: The value of thread is invalid
+ *
+ * EREJECT: the attachment of the thread to the frsh schehduler
+ * was rejected by the frsh scheduler possibly because of
+ * incorrect attributes, or because the requested minimum
+ * capacity cannot be guaranteed
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_ads_set_appscheduled
+ (frsh_thread_id_t thread,
+ bool appscheduled);
+
+/**
+ * fosa_ads_getappscheduled()
+ *
+ * Dynamically get the appscheduled attribute of a thread
+ *
+ * This function is used to dynamically get the appscheduled attribute
+ * of the thread identified by thread. This attribute controls the
+ * kind of scheduling used for threads created with it. If true, the
+ * thread is scheduled by the application scheduler. If not, it is
+ * scheduled by the system under a fixed priority scheduler
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * EINVAL: The value of thread is invalid
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_ads_get_appscheduled
+ (frsh_thread_id_t thread,
+ bool *appscheduled);
+
+
+/**
+ * fosa_ads_setappschedparam()
+ *
+ * Dynamically set the appsched_param attribute of a thread
+ *
+ * This function is used to dynamically set the appsched_param
+ * attribute of the thread identified by thread. For those threads
+ * with appscheduled set to true, this attribute represents the
+ * application-specific scheduling parameters. If successful, the
+ * function shall set the size of the appsched_param attribute to the
+ * value specified by paramsize, and shall copy the scheduling
+ * parameters occupying paramsize bytes and pointed to by param into
+ * that attribute
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * EINVAL: The value of thread is invalid, or paramsize is less than
+ * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_ads_set_appschedparam
+ (frsh_thread_id_t thread,
+ const void *param,
+ size_t paramsize);
+
+/**
+ * fosa_ads_get_appsched_params()
+ *
+ * Dynamically get the appsched_param attribute of a thread
+ *
+ * This function is used to dynamically get the appsched_param
+ * attribute of the thread identified by thread. For those threads
+ * with appscheduled set to true, this attribute represents the
+ * application-specific scheduling parameters. If successful, the
+ * function shall set the variable pointed to by paramsize to the size
+ * of the appsched_param attribute, and shall copy the scheduling
+ * parameters occupying paramsize bytes into the variable pointed to
+ * by param. This variable should be capable of storing a number of
+ * bytes equal to paramsize.
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * EINVAL: The value of thread is invalid, or paramsize is less than
+ * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications.
+ **/
+int fosa_ads_get_appsched_params
+ (frsh_thread_id_t thread,
+ void *param,
+ size_t *paramsize);
+
+
+/*********************************
+ * ADS actions
+ *
+ * A scheduling actions object is used to specify a series of actions
+ * to be performed by the system at the end of a scheduler primitive
+ * operation. The order of the actions added to the object shall be
+ * preserved.
+ *
+ *********************************/
+
+/**
+ * fosa_adsactions_add_reject()
+ *
+ * Add a reject-thread action
+ *
+ * This function adds a thread-reject action to the object referenced
+ * by sched_actions, that will serve to notify that the thread
+ * identified by thread has not been accepted by the scheduler to be
+ * scheduled by it, possibly because the thread contained invalid
+ * application scheduling attributes, or because there are not enough
+ * resources for the new thread. At the end of the new_thread()
+ * scheduler primitive operation, the parent of the rejected thread
+ * waiting on a fosa_thread_create() or the rejected thread itself
+ * waiting on a fosa_ads_set_appscheduled() function shall complete the
+ * function with an error code of EREJECT. If no reject-thread action
+ * is added during the new_thread() scheduler primitive operation, the
+ * thread is accepted to be scheduled by the scheduler and the
+ * associated fosa_thread_create() or the fosa_ads_set_appscheduled()
+ * function shall be completed without error. For the function to
+ * succeed, it has to be called from the new_thread() primitive
+ * operation and for the thread that is requesting attachment to the
+ * scheduler.
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * ENOMEM: There is insufficient memory to add this action
+ * EPOLICY: The thread specified by thread is not the one requesting
+ * attachment to the scheduler, or the function is not being
+ * called from the new_thread primitive operation
+ * EINVAL: The value specified by sched_actions is invalid
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_adsactions_add_reject(
+ fosa_ads_actions_t *sched_actions,
+ frsh_thread_id_t thread);
+
+/**
+ * fosa_adsactions_add_activate()
+ *
+ * Add a thread-activate action
+ *
+ * This function adds a thread-activate action to the object
+ * referenced by sched_actions. In case the thread had been previously
+ * suspended via posix_appsched_actions_addsuspend(), it will be
+ * activated at the end of the primitive operation.
+ *
+ * In those implementations that do not support urgency scheduling,
+ * the urgencu value is ignored. These implementations cannot support
+ * the frsh hierarchical scheduling module.
+ *
+ * In those implementations supporting urgency-scheduling, the action
+ * will cause the change of the urgency of the thread to the value
+ * specified in the urgency argument. Besides, if the thread was
+ * already active at the time the thread-activate action is executed,
+ * the change or urgency will imply a reordering of the thread in its
+ * priority queue, so that for threads of the same priority, those
+ * with more urgency will be scheduled before those of less urgency.
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * ENOMEM: There is insufficient memory to add this action
+ * EPOLICY: The thread specified by thread has its appscheduled
+ * attribute set to false,
+ * EINVAL: The value specified by sched_actions is invalid
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_adsactions_add_activate(
+ fosa_ads_actions_t *sched_actions,
+ frsh_thread_id_t thread,
+ fosa_ads_urgency_t urgency);
+
+/**
+ * fosa_adsactions_add_suspend()
+ *
+ * Add a thread-suspend action
+ *
+ * This function adds a thread-suspend action to the object referenced
+ * by sched_actions, that will cause the thread identified by thread
+ * to be suspended waiting for a thread-activate action at the end of
+ * the scheduler operation. If the thread was already waiting for a
+ * thread-activate action the thread-suspend action has no effect. It
+ * is an error trying to suspend a thread that is blocked by the
+ * operating system.
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * ENOMEM: There is insufficient memory to add this action
+ * EPOLICY: The thread specified by thread has its appscheduled
+ * attribute set to false,
+ * EINVAL: The value specified by sched_actions is invalid
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_adsactions_add_suspend(
+ fosa_ads_actions_t *sched_actions,
+ frsh_thread_id_t thread);
+
+/**
+ * fosa_adsactions_add_timeout()
+ *
+ * Add a timeout action
+ *
+ * This function adds a timeout action to the object referenced by
+ * sched_actions, that will cause the timeout() scheduler operation to
+ * be invoked if no other scheduler operation is invoked before
+ * timeout expires. The timeout shall expire when the clock specified by
+ * clock_id reaches the absolute time specified by the at_time
+ * argument.
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * ENOMEM: There is insufficient memory to add this action
+ * EPOLICY: The thread specified by thread has its appscheduled
+ * attribute set to false,
+ * EINVAL: The value specified by sched_actions is invalid
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_adsactions_add_timeout(
+ fosa_ads_actions_t *sched_actions,
+ fosa_clock_id_t clock_id,
+ const struct timespec *at_time);
+
+/**
+ * fosa_adsactions_add_thread_notification()
+ *
+ * Add a timed-thread-notification action
+ *
+ * This function adds a thread-notification action associated with the
+ * thread specified in the thread argument that will cause the
+ * notification_for_thread() scheduler operation to be invoked at the
+ * time specified by at_time. This operation shall be invoked when the
+ * clock specified by clock_id reaches the absolute time specified by
+ * the at_time argument. In particular, a cpu-time clock may be used
+ * for parameter clock_id.Only one thread-notification can be active
+ * for each thread and clock. Calling the function shall remove the
+ * former thread-notification, if any, that had been programmed for
+ * the same thread and clock. A value of NULL for parameter at_time is
+ * used to cancel a previous thread-notification, if any, for the
+ * thread specified by thread and the clock specified by clock_id.
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * ENOMEM: There is insufficient memory to add this action
+ * EPOLICY: The thread specified by thread has its appscheduled
+ * attribute set to false,
+ * EINVAL: The value specified by sched_actions is invalid
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_adsactions_add_thread_notification(
+ fosa_ads_actions_t *sched_actions,
+ frsh_thread_id_t thread,
+ fosa_clock_id_t clock_id,
+ const struct timespec *at_time);
+
+
+/**
+ * fosa_ads_set_handled_signal_set()
+ *
+ * Specifiy the set of signals that will be handled by the application
+ * scheduler
+ *
+ * This function is used to dynamically set the set of signals that
+ * are handled by the application scheduler. When a signal included
+ * in this set is generated, the signal() primitive operation of the
+ * application scheduler shall be executed. When a signal in tis set
+ * is generated, it shall always imply the execution of the signal()
+ * primitive operation, regardless of whether that signal could be
+ * accepted by some other thread. Once the signal() primitive
+ * operation is executed the signal is consumed, so no signal handlers
+ * shall be executed and no threads using a sigwait operation shall
+ * return for that particular signal instance. For this function to
+ * succeed, it has to be called from a primitive operation of a
+ * scheduler.
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * EPOLICY: The function has not been called from a scheduler
+ * primitive operation
+ * EINVAL: The value specified by set is invalid
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_ads_set_handled_signal_set(frsh_signal_t set[]);
+
+
+/**
+ * fosa_ads_invoke_withdata()
+ *
+ * Explicitly invoke the scheduler, with data
+ *
+ * This function can be used by any thread in the process to invoke
+ * the ads scheduler or to share data with it.
+ *
+ * If successful, the function shall cause the execution of the
+ * primitive operation explicit_call_with_data() of the ads scheduler
+ * with its thread parameter equal to the thread ID of the calling
+ * thread, and its msg_size parameter equal to msg_size. In addition,
+ * if msg_size is larger than zero, the function shall make available
+ * to the scheduler a memory area whose contents are identical to the
+ * memory area pointed to by msg in the msg parameter of the
+ * explicit_call_with_data() primitive operation (note that copying
+ * the information is not needed).
+ *
+ * The function shall not return until the system has finished
+ * execution of the explicit_call_with_data() primitive operation. If
+ * the reply argument is non NULL, the memory area pointed to by the
+ * reply parameter of explicit_call_with_data() primitive operation is
+ * copied into the memory area pointed to by reply, and its size is
+ * copied into the variable pointed to by reply_size. The size of the
+ * reply information is limited to the value FOSA_ADS_SCHEDINFO_MAX.
+ *
+ * The function shall fail if the size specified by msg_size is larger
+ * than FOSA_ADS_SCHEDINFO_MAX. The function shall fail if primitive
+ * operation explicit_call_with_data() is set to NULL for the ads
+ * scheduler.
+ *
+ * Returns 0 if successful; otherwise it returns an error code:
+ * EPOLICY: The function been called from inside a scheduler
+ * primitive operation
+ * EINVAL: The value of msg_size is less than zero or larger than
+ * FOSA_ADS_SCHEDINFO_MAX
+ * EMASKED: The operation cannot be executed because the primitive
+ * operation explicit_call_with_data() is set to NULL
+ *
+ * Alternatively, in case of error the implementation is allowed to
+ * notify it to the system console and then terminate the FRSH
+ * implementation and dependant applications
+ **/
+int fosa_ads_invoke_withdata
+ (const void *msg, size_t msg_size, void *reply, size_t *reply_size);
+
+/*}*/
+
+
+#endif /* !FOSA_APP_DEF_SCHED_H_ */