1,11 → 1,3 |
/** |
@file This file contains the functions and definitions for the core |
module. |
|
The file contains all fuinctions and data structures for the core |
module of the FSF. |
*/ |
|
//fsf_core.h |
//================================================================= |
// FFFFFFIII RRRRR SSTTTTTTT |
19,11 → 11,33 |
// Basic FSF(FIRST Scheduling Framework) contract management |
//================================================================ |
|
/** |
\defgroup core Core module |
|
This module includes the basic functions and services that are |
provided by any FSF implementation. This module includes basic type |
definitions, and functions to |
|
- create a contract and initialize it |
- set/get the basci parameters of a contract |
- negotiate a service contract, obtaining a server id |
- create and bind threads to servers |
- create/destroy a synchronization object |
- manage bounded workloads |
*/ |
/*@{*/ |
|
/** |
\file fsf_core.h |
|
This file contains the types, definitions and function prototypes |
for the core module of the First Scheduling Framework. |
*/ |
|
#include <time.h> |
#include <pthread.h> |
#include <sys/types.h> |
#include <stdbool.h> |
#include "stdbool.h" |
|
#include "fsf_configuration_parameters.h" |
#include "fsf_opaque_types.h" |
33,36 → 47,12 |
#define _FSF_CORE_H_ |
|
|
////////////////////////////////////////////////////////////////////// |
// INITIALIZATION SERVICES |
////////////////////////////////////////////////////////////////////// |
///////////////////////////////////////////////////////////////// |
// BASIC TYPES AND CONSTANTS are in fsf_basic_types.h |
///////////////////////////////////////////////////////////////// |
|
/** |
\ingroup coremodule |
|
\defgroup core_init Initialization and utilities |
|
@{ |
*/ |
|
/** |
We cannot call any fsf functions before fsf_init. After calling |
fsf_init, the main will be executing in the background. Then, it |
can do the negotiations, create the threads and, if needed, |
activate them via some user-specified synchronization mechanism. It |
may also create a contract for itself. The second time this |
function is called it fails. |
|
@retval 0 if the system is initialized |
@retval FSF_ERR_SYSTEM_ALREADY_INITIALIZED if the function has already |
been called before |
|
@retval others It may also return any of the errors that may be |
returned by the underlying operating system primitives |
required to perform the FSF system start up |
*/ |
int fsf_init(); |
|
/** |
This function converts an error code to an error message that is |
stored in the buffer starting at the location pointed to by |
72,20 → 62,18 |
truncated or not, a final zero character that marks the end of the |
string is stored in the buffer. The function fails if the error |
code passed does not correspond to any of the fsf error codes. |
|
@retval FSF_ERR_BAD_ARGUMENT error is not a valid value |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : error is not a valid value |
] |
*/ |
int fsf_strerror (int error, char *message, size_t size); |
|
/* @} */ |
|
///////////////////////////////////////////////////////////// |
// CONTRACT PARAMETERS |
///////////////////////////////////////////////////////////// |
|
/** |
\ingroup coremodule |
\defgroup core_contract Contract Creation and Initialization. |
\defgroup contract Contract Creation and Initialization. |
|
These functions are used to create and initialize a contract, and |
set its parameters. |
103,17 → 91,21 |
The operation receives a pointer to a contract parameters object |
and initializes it, setting it to the default values. |
The default values are: |
- budget min and max are set to 0; |
- period min and max are set to 0; |
- the workload is unbounded (FSF_INDETERMINATE); |
- the server deadline is equal to the period; |
- the budget and deadline overrun are not notified; |
- the granularity is set to "continuous"; |
- the quality and importance are set to the default values; |
- the scheduling policy is FSF_NONE. |
- budget min and max are set to 0 |
- period min and max are set to 0 |
- the workload is unbounded (FSF_INDETERMINATE) |
- the server deadline is equal to the period |
- the budget and deadline overrun are not notified |
- the granularity is set to "continuous" |
- the quality and importance are set to the default values |
(PEPPE: implementation dependent??) |
- the scheduling policy is FSF_NONE |
|
@param contract the pointer to the contract variable. |
@retval FSF_ERR_BAD_ARGUMENT contract is NULL |
@returns (PEPPE: should not return anything! change to void??) |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : contract is NULL |
] |
*/ |
int fsf_initialize_contract (fsf_contract_parameters_t *contract); |
|
150,16 → 142,20 |
fsf_schedule_timed_job() operation), while indeterminate tasks are |
not; therefore, their programming model is quite different). |
|
@param contract the pointer to the contract object |
@param contract the pointer to the contract object |
@param [in] budget_min the minimum budget for the contract |
@param [in] period_max the maximum period for the contract |
@param [in] workload the kind of workload (can be FSF_BOUNDED or |
FSF_INDETERMINATE) |
@param [in] workload the kind of workload (can be FSF_BOUNDED, |
FSF_INDETERMINATE or FSF_OVERHEAD) |
|
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if any of the pointers is NULL |
@returns 0 if the operation is succesful |
@returns FSF_ERR_BAD_ARGUMENT if some of the arguments is not in |
the expected range |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if any of the pointers is NULL |
or if only one of the timespec values is 0, and also if the workload |
is not a proper value (FSF_INDETERMINATE or FSF_BOUNDED) |
is not a proper value (FSF_INDETERMINATE, FSF_BOUNDED, or FSF_OVERHEAD) |
] |
*/ |
int |
fsf_set_contract_basic_parameters |
168,6 → 164,7 |
const struct timespec *period_max, |
fsf_workload_t workload); |
|
|
/** |
This operation obtains from the specified contract parameters |
object its budget, period, and workload, and copies them to the |
181,7 → 178,10 |
@param[out] workload pointer to the variable that will contain the |
workload type |
|
@retval FSF_ERR_BAD_ARGUMENT : if contract is NULL |
@returns (PEPPE: this should return nothing!) |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if contract is NULL |
] |
*/ |
int |
fsf_get_contract_basic_parameters |
222,13 → 222,17 |
This parameters is not used if the budget_overrun_sig_notify |
parameters is set to NULL_SIGNAL |
|
@retval 0 if the operation is succesful |
@retval FSF_BAD_ARGUMENT if contract is NULL or |
@returns 0 if the operation is succesful |
@returns FSF_BAD_ARGUMENT if some argument is out of range or not |
admissible. |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if contract is NULL or |
(d_equals_t is true and deadline is not FSF_NULL_DEADLINE) or |
(budget_overrun_sig_notify is not a valid signal) or |
(deadline_miss_sig_notify is not a valid signal) or |
(d_equals_t is false but (deadline is FSF_NULL_DEADLINE or its value |
is grater than the contract´s maximum period)) |
is grater than the contract´s maximum period))) |
] |
|
@see sigexplanation |
*/ |
247,9 → 251,10 |
specified contract parameters object. If d_equals_t is true, the |
deadline will not be updated. |
|
@retval FSF_ERR_BAD_ARGUMENT if contract is NULL |
|
@see fsf_set_contract_timing_requirements |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if contract is NULL |
] |
|
*/ |
int |
fsf_get_contract_timing_requirements |
269,23 → 274,7 |
|
|
/** |
\ingroup coremodule |
|
\defgroup core_synch Synchronization objects |
|
These objects are used to synchronize threads belonging to bounded |
workload servers. |
|
In the future we may add a broadcast operation that would signal a |
group of synchronization objects. We have not included a broadcast |
service in this version because it can be easily created by the |
user by signalling individual synchronization objects inside a |
loop. |
|
Notice that for synchronization objects there is no naming service |
like in shared objects because tasks that use synchronization are |
not developed independently, as they are closely coupled. |
|
\defgroup synch Synchronization objects |
*/ |
/*@{*/ |
/** |
304,50 → 293,55 |
variable managed by the scheduler, and returns a handle to it in |
the variable pointed to by synch_handle. |
|
@param[out] synch_handle pointer to the variable that will contain |
the handle to the newly created synchronization object |
@param[out] pointer to the variable that will contain the handle to the |
newly created synchronization object |
|
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if synch_handle is 0 |
@retval FSF_ERR_TOO_MANY_SYNCH_OBJS if the number of synchronization |
objects in the system has already exceeded the maximum |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong |
or not running |
@returns 0 if the operation is succesful |
@returns FSF_ERR_TOO_MANY_SYNCH_OBJS if the number of synchronization |
objects in the system has already exceeded the maximum |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if synch_handle is 0 |
FSF_ERR_TOO_MANY_SYNCH_OBJS : if the number of synchronization |
objects in the system has already exceeded the maximum |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
] |
|
*/ |
int |
fsf_create_synch_obj |
(fsf_synch_obj_handle_t *synch_handle); |
|
|
/** |
|
This function sends a notification to the synchronization object |
specified as parameter. If there is at least one server waiting on |
the synchronization object, the corresponding thread is unblocked, |
and the server rules for budget recharging apply. |
specified as parameter. If there is at least one thread waiting on |
the synchronization object, it is awaken. If more than one thread |
is waiting, just one of them is awaken. However, which one is |
awaken is implementation dependent. If no thread is waiting on the |
synchronization object, the notification is queued. |
|
If more than one server is waiting, just one of them is woken. |
However, which one is woken is implementation dependent. |
|
If no thread is waiting on the synchronization object, the |
notification is queued. |
|
[JULIO: all the ocurrrences of the word "thread" should be changed |
by "server" in the paragraph above |
] |
@param [in] synch_handle the handle of the synchronization object to |
notify. |
|
@retval 0 if the operation is completed succesfully |
@retval FSF_ERR_BAD_ARGUMENT if synch_handle is 0 |
@retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread |
is not scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_TOO_MANY_EVENTS_IN_SYNCH_OBJ if the number of |
events stored in the synchronization object reaches the |
maximum defined in the configuration parameter header file |
@returns 0 if the operation is completed succesfully |
@returns FSF_ERR_INVALID_SYNCH_OBJ_HANDLE is the handle is not valid |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if synch_handle is 0 |
FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_TOO_MANY_EVENTS_IN_SYNCH_OBJ : if the number of events stored |
in the synchronization object reaches the maximum defined in the |
configuration parameter header file |
] |
|
@see fsf_schedule_triggered_job, fsf_timed_schedule_triggered_job |
@sa fsf_schedule_triggered_job, fsf_timed_schedule_triggered_job |
*/ |
int |
fsf_signal_synch_obj |
363,22 → 357,33 |
@param synch_handle the handle to the synchronization object |
to be destroyed |
|
@retval 0 if the operation is succesful |
@retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE is the handle is not valid |
@retval FSF_ERR_BAD_ARGUMENT if synch_handle is 0 |
@retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
@returns 0 if the operation is succesful |
@returns FSF_ERR_INVALID_SYNCH_OBJ_HANDLE is the handle is not valid |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if synch_handle is 0 |
FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
] |
|
@see fsf_create_synch_obj |
@sa fsf_create_synch_obj |
*/ |
int |
fsf_destroy_synch_obj |
(fsf_synch_obj_handle_t synch_handle); |
|
// In the future we may add a broadcast operation that would signal a |
// group of synchronization objects. We have not included a broadcast |
// service in this version because it can be easily created by the |
// user by signalling individual synchronization objects inside a |
// loop. |
|
// Notice that for synchronization objects there is no naming service |
// like in shared objects because tasks that use synchronization are |
// not developed independently, as they are closely coupled. |
|
|
//////////////////////////////////////////////////// |
// SCHEDULING BOUNDED WORKLOADS |
//////////////////////////////////////////////////// |
432,7 → 437,7 |
parameter is set to NULL, no action is |
taken. |
|
@param [out] was_budget_overran upon return of this function, the |
@param [out] was_budget_overrun upon return of this function, the |
variable pointed by this function will be |
equal to true if the previous server budget was |
overrun, to false otherwise. If this |
439,19 → 444,24 |
parameter is set to NULL, no action is |
taken. |
|
@retval 0 if the operation is succesful |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF |
@returns 0 if the operation is succesful |
@returns FSF_ERR_TIME_SPEC_IN_THE_PAST if the absolute time specification |
is in the past. |
[ERR@RETURNED: |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF |
main scheduler |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is |
not scheduled under the FSF |
@retval FSF_ERR_UNBOUND if the calling thread does not have a valid |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled |
under the FSF |
FSF_ERR_NOT_BOUND_THREAD : if the calling thread does not have a valid |
server bound to it |
@retval FSF_ERR_BAD_ARGUMENT if the workload of the server is not |
FSF_BOUNDED |
FSF_ERR_BAD_ARGUMENT : if abs_time is NULL |
FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the server |
is not FSF_BOUNDED |
] |
|
@sa fsf_schedule_triggered_job, fsf_timed_schedule_triggered_job |
|
*/ |
int |
fsf_schedule_timed_job |
461,6 → 471,7 |
bool *was_deadline_missed, |
bool *was_budget_overran); |
|
|
/** |
This operation is invoked by threads associated with bounded |
workload servers to indicate that a job has been completed (and |
471,62 → 482,34 |
server will wait upon the specified synchronization object, the |
server's budget will be made zero for the remainder of the server's |
period, and the implementation will not replenish the budget until |
the specified synchronization object is signalled. |
the specified synchronization object is signalled. At that time, |
all pending budget replenishments (if any) are made effective. Once |
the server has a positive budget and the scheduler schedules the |
calling thread again, the call returns and at that time, except for |
those parameters equal to NULL pointers, the system reports the |
current period and budget for the current job, whether the deadline |
of the previous job was missed or not, and whether the budget of |
the previous job was overrun or not. |
|
At that time, all pending budget replenishments (if any) are made |
effective. Once the server has a positive budget and the scheduler |
schedules the calling thread again, the call returns and at that |
time, except for those parameters equal to NULL pointers, the |
system reports the current period and budget for the current job, |
whether the deadline of the previous job was missed or not, and |
whether the budget of the previous job was overrun or not. |
|
In a system with hierarchical scheduling, since this call makes the |
budget zero, the other threads in the same server are not run. As |
mentioned above, only when the call finishes the budget may be |
replenished. |
|
@param [in] synch_handle handle of the synchronization object |
[ERR@RETURNED: |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF |
main scheduler |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled |
under the FSF |
FSF_ERR_NOT_BOUND_THREAD : if the calling thread does not have a valid |
server bound to it |
FSF_ERR_BAD_ARGUMENT : if the synch_handle given is not valid |
FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the server |
is not FSF_BOUNDED |
] |
|
@param [out] next_budget upon return of this function, the variable |
pointed by this function will be equal |
to the current server budget. If this |
parameter is set to NULL, no action is |
taken. |
@param [out] next_period upon return of this function, the variable |
pointed by this function will be equal to |
the current server period. If this parameter is |
set to NULL, no action is taken. |
|
@param [out] was_deadline_missed upon return of this function, the |
variable pointed by this function will be |
equal to true if the previous server deadline |
was missed, to false otherwise. If this |
parameter is set to NULL, no action is |
taken. |
|
@param [out] was_budget_overran upon return of this function, the |
variable pointed by this function will be |
equal to true if the previous server budget was |
overrun, to false otherwise. If this |
parameter is set to NULL, no action is |
taken. |
|
@retval 0 if the operation is succesful |
@retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of |
the FSF main scheduler |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread |
is not scheduled under the FSF |
@retval FSF_ERR_UNBOUND if the calling thread does not have |
a valid server bound to it |
@retval FSF_ERR_BAD_ARGUMENT if the workload of the server is not |
FSF_BOUNDED or the synch_handle given is not valid |
|
@sa fsf_schedule_triggered_job, fsf_schedule_timed_job |
|
*/ |
int |
fsf_schedule_triggered_job |
542,19 → 525,20 |
absolute timeout. The timed_out argument, indicates whether the |
function returned because of a timeout or not |
|
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction |
of the FSF main scheduler |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is |
not scheduled under the FSF |
@retval FSF_ERR_UNBOUND if the calling thread does not have a valid |
[ERR@RETURNED: |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF |
main scheduler |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled |
under the FSF |
FSF_ERR_NOT_BOUND_THREAD : if the calling thread does not have a valid |
server bound to it |
@retval FSF_ERR_BAD_ARGUMENT if the workload of the server is not |
FSF_BOUNDED, the synch_handle given is not valid or the abs_timeout |
argument is NULL or its value is in the past |
FSF_ERR_BAD_ARGUMENT : if the synch_handle given is not valid or the |
abs_timeout argument is NULL or its value is in the past |
FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the server |
is not FSF_BOUNDED |
] |
|
@see fsf_schedule_triggered_job |
*/ |
int |
fsf_timed_schedule_triggered_job |
566,6 → 550,9 |
bool *was_deadline_missed, |
bool *was_budget_overran); |
|
|
|
|
/*@}*/ |
|
/////////////////////////////////////////////////////////////////// |
573,13 → 560,13 |
/////////////////////////////////////////////////////////////////// |
|
/** |
\ingroup coremodule |
\defgroup negotiate Negotiate contract functions |
|
\defgroup core_negotiate Negotiate contract functions |
|
The following functions are used to create servers for a contract |
parameters specification and also to assign one or more threads to |
a server. |
a server (Note: the current implementation only supports one thread |
per server; this limitation will be removed in the next phase of |
the project) |
*/ |
/*@{*/ |
|
595,6 → 582,7 |
*/ |
typedef void * (*fsf_thread_code_t) (void *); |
|
|
/** |
The operation negotiates a contract for a new server. If the |
on-line admission test is enabled it determines whether the |
601,31 → 589,27 |
contract can be admitted or not based on the current contracts |
established in the system. Then it creates the server and |
recalculates all necessary parameters for the contracts already |
present in the system. |
present in the system. This is a potentially blocking operation; it |
returns when the system has either rejected the contract, or |
admitted it and made it effective. It returns zero and places the |
server identification number in the location pointed to by the |
server input parameter if accepted, or an error if rejected. No |
thread is bound to the newly created server, which will be idle |
until a thread is bound to it. This operation can only be executed |
by threads that are already bound to an active server and therefore |
are being scheduled by the fsf scheduler. |
|
This is a potentially blocking operation; it returns when the |
system has either rejected the contract, or admitted it and made it |
effective. It returns zero and places the server identification |
number in the location pointed to by the server input parameter if |
accepted, or an error if rejected. No thread is bound to the newly |
created server, which will be idle until a thread is bound to |
it. This operation can only be executed by threads that are already |
bound to an active server and therefore are being scheduled by the |
fsf scheduler. |
[ERR@RETURNED: |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF |
main scheduler |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled |
under the FSF |
FSF_ERR_BAD_ARGUMENT : if the contract or server arguments are NULL |
FSF_ERR_TOO_MANY_SERVERS : if there is no space for more servers |
(the maximum number of them is already reached) |
] |
|
@param [in] contract pointer to the contract |
@param [out] server server id |
|
@retval 0 if the call is succesful |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF |
main scheduler |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD |
if the calling thread is not scheduled |
under the FSF |
@retval FSF_ERR_BAD_ARGUMENT if the contract or server arguments |
are NULL |
*/ |
int |
fsf_negotiate_contract |
632,6 → 616,7 |
(const fsf_contract_parameters_t *contract, |
fsf_server_id_t *server); |
|
|
/** |
This operation negotiates a contract for a new server, creates a |
thread and binds it to the server. If the contract is accepted, the |
640,32 → 625,26 |
POSIX function call, and attaches it to the fsf scheduler. Then, it |
binds the created thread to the new server. It returns zero and |
puts the server identification number in the location pointed to by |
the server input parameter. |
the server input parameter. The attr parameter is overwritten as |
necessary to introduce the adequate scheduling policy and priority, |
according to the preemption level given in the contract and the |
fsf_priority_map() function defined by the user. If the contract is |
rejected, the thread is not created and the corresponding error is |
returned. |
|
The attr parameter is overwritten as necessary to introduce the |
adequate scheduling attributes, according to the information given |
in the contract. |
|
The server is created with the FSF_NONE scheduling policy, which |
means no hierarchical scheduling, and only one thread per server, |
except for the case of background tasks (see below) |
|
If the contract is rejected, the thread is not created and the |
corresponding error is returned. |
|
@param [in] contract pointer to the contract |
@param [out] server server id |
@param [out] thread thread id |
@param [in] attr threads attributes |
@param [in] thread_code pointer to the function that implements |
the thread |
@param [in] arg arguments for the thread |
|
@retval FSF_ERR_BAD_ARGUMENT if the contract or server arguments are NULL |
@retval FSF_ERR_CONTRACT_REJECTED if the contract is rejected |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if the contract or server arguments are NULL |
FSF_ERR_CONTRACT_REJECTED : if the contract is rejected. |
FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload |
in the contract is FSF_OVERHEAD |
|
@retval others it may also return all the errors that may be returned |
by the pthread_create()POSIX function call |
It may also return all the errors that may be returned by the |
pthread_create()POSIX function call |
] |
|
*/ |
int |
696,15 → 675,15 |
thread will have the SCHED_APP scheduling policy and will be |
attached to the fsf scheduler. |
|
@param [in] contract pointer to the contract |
@param [out] server id |
|
@retval 0 if the contract negotation is succesful |
@retval FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD if the thread is attached to |
[ERR@RETURNED: |
FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to |
an application defined scheduler different than the fsf scheduler |
@retval FSF_ERR_BAD_ARGUMENT if the contract or server arguments |
are NULL |
@retval FSF_ERR_CONTRACT_REJECTED if the contract is rejected. |
FSF_ERR_BAD_ARGUMENT : if the contract or server arguments are NULL |
FSF_ERR_CONTRACT_REJECTED : if the contract is rejected. |
FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload |
in the contract is FSF_OVERHEAD |
] |
|
*/ |
int |
fsf_negotiate_contract_for_myself |
713,10 → 692,11 |
|
|
/** |
This operation associates a thread with a server, which means that |
it starts consuming the server's budget and is executed according |
to the contract established for that server. If the thread is |
already bound to another server, and error is returned. |
fsf_bind_thread_to_server: This operation associates a thread with |
a server, which means that it starts consuming the server's budget |
and is executed according to the contract established for that |
server. If the thread is already bound to another server, it is |
effectively unbound from it and bound to the specified one. |
|
It fails if the server's policy is different than FSF_NONE, or if |
there is already a thread bound to this server |
726,19 → 706,18 |
scheduling policy SCHED_APP and at the same time be attached to an |
application scheduler different than the fsf scheduler. |
|
@param [in] server id |
@param [in] thread id |
|
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction |
of the FSF main scheduler |
@retval FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD if the thread is attached to |
[ERR@RETURNED: |
FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF |
main scheduler |
FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to |
an application defined scheduler different than the fsf scheduler |
@retval FSF_ERR_BAD_ARGUMENT if the server value does not complain with the |
FSF_ERR_BAD_ARGUMENT : if the server value does not complain with the |
expected format or valid range or the given thread does not exist |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the referenced server |
is not valid |
@retval FSF_ERR_ALREADY_BOUND if the thread is already bound to |
another server. |
FSF_ERR_NOT_CONTRACTED_SERVER : if the referenced server is not valid |
FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload |
of the server is FSF_OVERHEAD |
FSF_ERR_ALREADY_BOUND : if the given server has a thread already bound |
] |
|
*/ |
int |
759,18 → 738,18 |
application scheduler, the thread is still attached to the fsf |
scheduler, but suspended. |
|
@param [in] thread thread id |
|
@retval 0 if the operation is succesful |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF |
[ERR@RETURNED: |
FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF |
main scheduler |
@retval FSF_ERR_BAD_ARGUMENT if the given thread does not exist |
@retval FSF_ERR_NOT_SCHEDULED_THREAD if the given thread is not scheduled |
FSF_ERR_BAD_ARGUMENT : if the given thread does not exist |
FSF_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled |
under the FSF |
@retval FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD if the thread is attached to |
FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to |
an application defined scheduler different than the fsf scheduler |
@retval FSF_ERR_NOT_BOUND if the given thread does not have a valid |
FSF_ERR_NOT_BOUND_THREAD : if the given thread does not have a valid |
server bound to it |
] |
|
*/ |
int |
fsf_unbind_thread_from_server (pthread_t thread); |
781,16 → 760,15 |
an error if the thread does not exist, it is not under the control |
of the scheduling framework, or is not bound. |
|
@param [in] thread thread id |
@param [out] server server |
|
@retval 0 if the operation is succesful |
@return FSF_ERR_NOT_SCHEDULED_THREAD if the given thread is not scheduled |
[ERR@RETURNED: |
FSF_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled |
under the FSF |
@return FSF_ERR_UNBOUND if the given thread does not have a valid |
FSF_ERR_NOT_BOUND_THREAD : if the given thread does not have a valid |
server bound to it |
@return FSF_ERR_BAD_ARGUMENT if the given thread does not exist or the |
FSF_ERR_BAD_ARGUMENT : if the given thread does not exist or the |
server argument is NULL |
] |
|
*/ |
int |
fsf_get_server |
802,18 → 780,16 |
with the specified server in the variable pointed to by |
contract. It returns an error if the server id is incorrect. |
|
@param [in] server server id |
@param [out] contract pointer to the contract structure |
|
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if the contract argument is |
NULL or the value of the server argument is not in range |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if the contract argument is NULL or the value |
of the server argument is not in range |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread |
has been cancelled or it is not valid |
] |
|
*/ |
int |
fsf_get_contract |
826,16 → 802,15 |
remaining in the system. This is a potentially blocking operation; |
it returns when the system has made the changes effective. |
|
@param [in] server server id |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if the value of server is not in range |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread |
has been cancelled or it is not valid |
] |
|
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if the value of server is not in range |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
has been cancelled or it is not valid |
*/ |
int |
fsf_cancel_contract (fsf_server_id_t server); |
853,18 → 828,16 |
either rejected the new contract, or admitted it and made it |
effective. |
|
@param [in] new_contract a pointer to the new contract |
@param [in] server server id |
|
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if the new_contract argument is NULL or the |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if the new_contract argument is NULL or the |
value of the server argument is not in range |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread |
has been cancelled or it is not valid |
] |
|
*/ |
int |
fsf_renegotiate_contract |
871,44 → 844,34 |
(const fsf_contract_parameters_t *new_contract, |
fsf_server_id_t server); |
|
|
/** |
The operation enqueues a renegotiate operation for an existing |
server, and returns immediately. The renegotiate operation is |
performed asynchronously and the calling thread may continue |
executing normally. Of course, wheter the operation is performed |
immediately or not depends on the relative priority of the service |
thread and the calling thread, on the scheduler used, etc. |
performed asynchronously, as soon as it is practical; meanwhile the |
system operation will continue normally. When the renegotiation is |
made, if the on-line admission test is enabled it determines |
whether the contract can be admitted or not based on the current |
contracts established in the system. If it cannot be admitted, the |
old contract remains in effect. If it can be admitted, it |
recalculates all necessary parameters for the contracts already |
present in the system. When the operation is completed, |
notification is made to the caller, if requested, via a signal. The |
status of the operation (in progress, admitted, rejected) can be |
checked with the get_renegotiation_status operation. The argument |
sig_notify can be NULL_SIGNAL (no notification), or any posix |
signal; and in this case sig_value is to be sent with the signal. |
|
When the renegotiation is completed, if the on-line admission test |
is enabled it determines whether the contract can be admitted or |
not based on the current contracts established in the system. If it |
cannot be admitted, the old contract remains in effect. If it can |
be admitted, it recalculates all necessary parameters for the |
contracts already present in the system. When the operation is |
completed, notification is made to the caller, if requested, via a |
signal. The status of the operation (in progress, admitted, |
rejected) can be checked with the get_renegotiation_status |
operation. The argument sig_notify can be NULL_SIGNAL (no |
notification), or any POSIX signal; and in this case sig_value is |
to be sent with the signal. |
|
@param [in] new_contract pointer to the new contract to be negotiated |
@param [in] server server id |
@param [in] sig_notify NULL (no signal) or any POSIX signal |
@param [in] sig_value a sigval structure that contains values to be |
passed to the signal handler. Valid only if sig_notify |
is different from NULL. |
|
@retval 0 if the call is succesful |
@retval FSF_ERR_BAD_ARGUMENT if the new_contract argument is NULL, the |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if the new_contract argument is NULL, the |
value of the server argument is not in range or sig_notify is |
neither NULL nor a valid POSIX signal |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread |
has been cancelled or it is not valid |
] |
|
*/ |
int |
918,32 → 881,25 |
int sig_notify, |
union sigval sig_value); |
|
/** |
Possible values returned by fsf_get_renegotiation_status |
*/ |
typedef enum {FSF_IN_PROGRESS, |
FSF_REJECTED, |
FSF_ADMITTED} |
fsf_renegotiation_status_t; |
|
/** |
The operation reports on the status of the last renegotiation |
operation enqueued for the specified server. It is callable even |
after notification of the completion of such operation, if |
requested. |
requested. If the fsf_request_contract_renegotiation operation has |
not ever been called for the given server the status returned is |
FSF_NOT_REQUESTED |
|
@param [in] server server id |
@param [out] renegotiation_status the status of the renegotiation; |
|
@retval 0 if succesful completion; |
@retval FSF_ERR_BAD_ARGUMENT if the renegotiation_status argument is |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if the renegotiation_status argument is |
NULL or the value of the server argument is not in range |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread |
has been cancelled or it is not valid |
] |
|
*/ |
int |
fsf_get_renegotiation_status |
950,62 → 906,6 |
(fsf_server_id_t server, |
fsf_renegotiation_status_t *renegotiation_status); |
|
|
//Data types |
|
/// List of contracts to negotiate |
typedef struct { |
int size; |
fsf_contract_parameters_t* contracts[FSF_MAX_N_SERVERS]; |
} fsf_contracts_group_t; |
|
/// List of servers to cancel |
typedef struct { |
int size; |
fsf_server_id_t servers[FSF_MAX_N_SERVERS]; |
} fsf_servers_group_t; |
|
|
/** |
This operation analizes the schedulability of the context that |
results from negitiating the contracts specified in the |
contracts_up list and cacelling the contracts referenced by the |
servers_down list. If the overall negotiation is successful, a new |
server will be created for each of the elements of the contracts_up |
group, the servers in servers_down will be cancelled, the list of |
new server ids will be returned in the variable pointed to by |
servers_up, and the variable pointed to by accepted will be made |
true. Otherwise, this variable will be made false, and no other |
effect will take place. The function returns the corresponding |
error code if any of the contracts is not correct or any of the |
server is is not valid. |
|
@param [in] contracts_up list of contracts to negotiate |
@param [in] servers_down list of contracts to be canceled |
@param [out] servers_up list of server ids that have been created, they are |
given in the same order as the contract_up list of contracts; |
@param [out] accepted if the operation is succesful; |
|
@retval 0 if succesful completion; |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF |
main scheduler |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is |
not scheduled under the FSF |
@retval FSF_ERR_BAD_ARGUMENT if any of the servers_up or accepted arguments |
is NULL, if the contracts_up and servers_down arguments are both NULL, |
or any of them has erroneous size or its elements are NULL or not in the |
valid range respectively |
*/ |
int |
fsf_negotiate_group |
(const fsf_contracts_group_t *contracts_up, |
const fsf_servers_group_t *servers_down, |
fsf_servers_group_t *servers_up, |
bool *accepted); |
|
|
/*@}*/ |
|
|
1015,20 → 915,9 |
|
|
/** |
\ingroup coremodule |
|
\defgroup core_sched_info Obtaining information from the scheduler. |
|
This group of function is used to get informations from the |
scheduler, like execution time of a task, remaining budget of a |
server, etc. |
|
@{ |
*/ |
|
/** |
Returns true if the system is configured with the on-line admission |
test enabled, or false otherwise. |
Returns true if the system is |
configured with the on-line admission test enabled, or false |
otherwise. |
*/ |
bool |
fsf_is_admission_test_enabled(); |
1038,20 → 927,16 |
threads bound to the specified server in the variable pointed to by |
cpu_time. |
|
@param [in] server server id |
@param [out] cpu_time pointer to a timespec structure that will contain |
the cpu time consumed by the threads that are bound to the |
specific server, since its creation. |
|
@retval 0 if succesful completion |
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is |
not in range or cpu_time is NULL |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or |
cpu_time is NULL |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread |
has been cancelled or it is not valid |
] |
|
*/ |
int |
fsf_get_cpu_time |
1061,21 → 946,18 |
/** |
This function stores in the variable pointed to by budget the |
remaining execution-time budget associated with the specified |
server. |
server |
|
@param [in] server server id |
@param [out] budget pointer to a timespec structure that will |
contain the remaining budget |
|
@retval 0 if succesful completion |
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is |
not in range or budget is NULL |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or |
budget is NULL |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread |
has been cancelled or it is not valid |
] |
|
*/ |
int |
fsf_get_remaining_budget |
1084,24 → 966,21 |
|
|
/** |
This function stores in the variables pointed to by budget and |
period, the execution-time budget and the period respectively |
associated with the specified server. If any of these pointers is |
NULL, the corresponding information is not stored. |
This function stores in the variables |
pointed to by budget and period, the execution-time budget and the |
period respectively associated with the specified server. If any of |
these pointers is NULL, the corresponding information is not stored. |
|
@param [in] server server id |
@param [out] budget budget available for the current server instance |
@param [out] period period available for the current server instance |
|
@retval 0 if succesful completion |
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is |
not in range, budget is NULL or period is NULL |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if the value of the server argument is not in range, |
or budget and period are both NULL |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread |
has been cancelled or it is not valid |
] |
|
*/ |
int |
fsf_get_budget_and_period |
1109,63 → 988,47 |
struct timespec *budget, |
struct timespec *period); |
|
/* @} */ |
|
|
///////////////////////////////////////////////////////////////////// |
// SERVICE THREAD TUNING |
///////////////////////////////////////////////////////////////////// |
|
/** |
\ingroup coremodule |
|
\defgroup core_service_thread Service Thread |
|
These functions are to the initialization and tuning of the service |
thread. |
|
Implementation dependency: in the fixed priority implementation of |
fsf, the default priority is lower than the priority of any server, |
but higher than the background. According to the |
implementation-dependent module the priority is adjustable by means |
of a function that changes its preemption level. |
|
@{ |
*/ |
|
|
/** |
This function allows the application to change the period and |
budget of the service thread that makes the |
This function allows the application to |
change the period and budget of the service thread that makes the |
negotiations. Increasing the utilization of this thread makes the |
negotiations faster, but introduces additional load in the system |
that may decrease the bandwidth available for the servers. For this |
call, the system will make a schedulability analysis to determine |
if the new situation is acceptable or not. This is reported back in |
the variable pointed to by accepted. If the new service thread data |
is accepted, the system will reassign budgets and periods to the |
servers according to the new bandwidth available, in the same way |
as it does for a regular contract negotiation. |
call, the system will make a schedulability analysis to determine if |
the new situation is acceptable or not. This is reported back in the |
variable pointed to by accepted. If the new service thread data is |
accepted, the system will reassign budgets and periods to the |
servers according to the new bandwidth available, in the same way as |
it does for a regular contract negotiation. |
|
When its budget is exhausted, the service thread may run in the |
background. |
background |
|
The service thread starts with a default budget and period that are |
configurable. |
configurable |
|
@param [in] budget budget for the service thread |
@param [in] period for the service thread |
@param [out] accepted true is the change has been accepted |
Implementation dependency: in the fixed priority implementtaion of |
fsf, the default priority is lower than the priority of any server, |
but higher than the background. According to the |
implementation-dependent module the priority is adjustable by means |
of a function that changes its preemption level |
|
|
@retval 0 is the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if any of the pointer arguments is NULL or |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL or |
the budget value is greater than the period value |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread |
has been cancelled or it is not valid |
] |
|
*/ |
int |
fsf_set_service_thread_data |
1177,17 → 1040,16 |
this function returns in the variables pointed by budget and |
period, respectively, the current budget and period of the service |
thread. |
|
@param [out] budget current budget of the service thread |
@param [out] period current period of the service thread |
|
@retval FSF_ERR_BAD_ARGUMENT if any of the pointer arguments is NULL |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
[ERR@RETURNED: |
FSF_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong |
or not running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread |
has been cancelled or it is not valid |
] |
|
*/ |
int |
fsf_get_service_thread_data |
1194,32 → 1056,109 |
(struct timespec *budget, |
struct timespec *period); |
|
/* @} */ |
|
//////////////////////////////////////////////////////////////////////// |
// BACKGROUND MANAGEMENT |
//////////////////////////////////////////////////////////////////////// |
|
//A round-robin background scheduling policy is available for those |
//threads that do not have real-time requirements. Because some of |
//these threads may require sharing information with other threads run |
//by regular servers, special background contracts may be created for |
//specifying the synchronization requirements. |
|
//The way of specifying a background contract is by setting budget_min |
//= period_max = 0. Negotiation may fail if the contract uses |
//shared_objects. If the contract has no shared_objects the returned |
//server id represents the background and may be used to bind more |
//than one thread. If the contract has shared objects a server is |
//created to keep track of them, but the associated threads are |
//executed in the background, together with the other background |
//threads |
|
|
//////////////////////////////////////////////////////////////////////// |
// CHANGE OF MODE: GROUPS OF CONTRACTS |
//////////////////////////////////////////////////////////////////////// |
|
//Data types |
|
//list of contracts to negotiate |
typedef struct { |
int size; |
fsf_contract_parameters_t* contracts[FSF_MAX_N_SERVERS]; |
} fsf_contracts_group_t; |
|
//list of servers to cancel |
typedef struct { |
int size; |
fsf_server_id_t servers[FSF_MAX_N_SERVERS]; |
} fsf_servers_group_t; |
|
|
/** |
This operation analizes the schedulability of |
the context that results from negitiating the contracts specified in |
the contracts_up list and cacelling the contracts referenced by the |
servers_down list. If the overall negotiation is successful, a new |
server will be created for each of the elements of the contracts_up |
group, the servers in servers_down will be cancelled, the list of |
new server ids will be returned in the variable pointed to by |
servers_up, and the variable pointed to by accepted will be made |
true. Otherwise, this variable will be made false, and no other |
effect will take place. The function returns the corresponding error |
code if any of the contracts is not correct or any of the server ids |
is not valid. |
Observe that in order to be able to receive the returned arguments, |
the calling thread's server should not be in the servers_down list. |
|
A round-robin background scheduling policy is available for those |
threads that do not have real-time requirements. Because some of |
these threads may require sharing information with other threads |
run by regular servers, special background contracts may be created |
for specifying the synchronization requirements. |
[ERR@RETURNED: |
FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running |
FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF |
main scheduler |
FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled |
under the FSF |
FSF_ERR_BAD_ARGUMENT : if any of the servers_up or accepted arguments |
is NULL, if the contracts_up and servers_down arguments are both NULL, |
or any of them has erroneous size or its elements are NULL or not in the |
valid range respectively |
] |
|
The way of specifying a background contract is by setting |
budget_min = period_max = 0. Negotiation may fail if the contract |
uses shared_objects. If the contract has no shared_objects the |
returned server id represents the background and may be used to |
bind more than one thread. If the contract has shared objects a |
server is created to keep track of them, but the associated threads |
are executed in the background, together with the other background |
threads |
*/ |
int |
fsf_negotiate_group |
(const fsf_contracts_group_t *contracts_up, |
const fsf_servers_group_t *severs_down, |
fsf_servers_group_t *severs_up, |
bool *accepted); |
|
@todo [PEPPE: this will be put in the general description of the core |
module] |
|
////////////////////////////////////////////////////////////////////// |
// INITIALIZATION SERVICES |
////////////////////////////////////////////////////////////////////// |
|
|
/** |
We cannot call any fsf functions before fsf_init. After calling |
fsf_init, the main will be executing in the background. Then, it |
can do the negotiations, create the threads and, if needed, |
activate them via some user-specified synchronization mechanism. It |
may also create a contract for itself. The second time this |
function is called it fails. |
|
[ERR@RETURNED: |
FSF_ERR_SYSTEM_ALREADY_INITIALIZED : if the function has already |
been called before |
|
It may also return any of the errors that may be returned by the |
underlying operating system primitives required to perform the |
FSF system start up |
] |
|
*/ |
int fsf_init(); |
|
/*@}*/ |
|
|
#endif // _FSF_CORE_H_ |