37,15 → 37,9 |
// INITIALIZATION SERVICES |
////////////////////////////////////////////////////////////////////// |
|
/** |
\ingroup coremodule |
/** |
\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, |
64,6 → 58,8 |
int fsf_init(); |
|
/** |
\ingroup coremodule |
|
This function converts an error code to an error message that is |
stored in the buffer starting at the location pointed to by |
message. The size of this buffer is specified by the size |
77,22 → 73,14 |
*/ |
int fsf_strerror (int error, char *message, size_t size); |
|
/* @} */ |
|
///////////////////////////////////////////////////////////// |
// CONTRACT PARAMETERS |
///////////////////////////////////////////////////////////// |
|
/** |
/** |
\ingroup coremodule |
\defgroup core_contract Contract Creation and Initialization. |
|
These functions are used to create and initialize a contract, and |
set its parameters. |
*/ |
/*@{*/ |
|
/** |
The operation receives a pointer to a contract parameters object |
and initializes it, setting it to the default values. |
The default values are: |
139,6 → 127,8 |
// granted_capacity_flag => false; |
|
/** |
\ingroup coremodule |
|
The operation updates the specified contract parameters object by |
setting its budget, period, and workload to the specified input |
parameters. (Note: the workload is a basic parameter because |
165,6 → 155,8 |
fsf_workload_t workload); |
|
/** |
\ingroup coremodule |
|
This operation obtains from the specified contract parameters |
object its budget, period, and workload, and copies them to the |
places pointed to by the corresponding input parameters. |
188,6 → 180,8 |
|
|
/** |
\ingroup coremodule |
|
The operation updates the specified contract parameters |
object, specifying the additional parameters requirements of |
a contract. |
239,6 → 233,8 |
union sigval deadline_miss_sig_value); |
|
/** |
\ingroup coremodule |
|
The operation obtains the corresponding input parameters from the |
specified contract parameters object. If d_equals_t is true, the |
deadline will not be updated. |
257,8 → 253,6 |
int *deadline_miss_sig_notify, |
union sigval *deadline_miss_sig_value); |
|
/*@}*/ |
|
////////////////////////////////////////////////////////////////// |
// SYNCHRONIZATION OBJECTS |
////////////////////////////////////////////////////////////////// |
267,33 → 261,6 |
/** |
\ingroup coremodule |
|
\defgroup core_synch Synchronization objects |
|
An abstract synchronization object is defined by the application. |
This object can be used by an application to wait for an event to |
arrive by invoking the fsf_schedule_triggered_job() operation. It |
can also be used to signal the event either causing a waiting |
server to wake up, or the event to be queued if no server is |
waiting for it. |
|
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. |
|
*/ |
/*@{*/ |
|
|
/** |
This operation creates and initializes a synchronization object |
variable managed by the scheduler, and returns a handle to it in |
the variable pointed to by synch_handle. |
315,6 → 282,7 |
(fsf_synch_obj_handle_t *synch_handle); |
|
/** |
\ingroup coremodule |
|
This function sends a notification to the synchronization object |
specified as parameter. If there is at least one server waiting on |
348,6 → 316,8 |
(fsf_synch_obj_handle_t synch_handle); |
|
/** |
\ingroup coremodule |
|
This operation destroys the synchronization object (created by a |
previous call to fsf_create_synch_obj) that is referenced by the |
synch_handle variable. After calling this operation, the |
378,6 → 348,8 |
//////////////////////////////////////////////////// |
|
/** |
\ingroup coremodule |
|
This operation is invoked by threads associated with bounded |
workload servers to indicate that a job has been completed (and |
that the scheduler may reassign the unused capacity of the current |
397,7 → 369,7 |
|
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 abobe, only when the call finishes the budget may be |
mentioned above, only when the call finishes the budget may be |
replenished. |
|
@param [in] abs_time absolute time at which the budget will be |
452,6 → 424,8 |
bool *was_budget_overran); |
|
/** |
\ingroup coremodule |
|
This operation is invoked by threads associated with bounded |
workload servers to indicate that a job has been completed (and |
that the scheduler may reassign the unused capacity of the current |
529,6 → 503,8 |
|
|
/** |
\ingroup coremodule |
|
This call is the same as fsf_schedule_triggered_job, but with an |
absolute timeout. The timed_out argument, indicates whether the |
function returned because of a timeout or not |
559,25 → 535,14 |
bool *was_deadline_missed, |
bool *was_budget_overran); |
|
/*@}*/ |
|
/////////////////////////////////////////////////////////////////// |
// CONTRACT NEGOCIATION OPERATIONS |
// CONTRACT NEGOTIATION OPERATIONS |
/////////////////////////////////////////////////////////////////// |
|
/** |
\ingroup coremodule |
|
\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. |
*/ |
/*@{*/ |
|
|
/** |
The operation negotiates a contract for a new server. If the |
on-line admission test is enabled it determines whether the |
contract can be admitted or not based on the current contracts |
619,6 → 584,8 |
fsf_server_id_t *server); |
|
/** |
\ingroup coremodule |
|
This operation negotiates a contract for a new server, creates a |
thread and binds it to the server. If the contract is accepted, the |
operation creates a thread with the arguments thread, attr, |
666,6 → 633,8 |
void *arg); |
|
/** |
\ingroup coremodule |
|
This operation negotiates a contract for a new server, and binds |
the calling thread to it. If the contract is accepted it returns |
zero and copies the server identification number in the location |
676,13 → 645,13 |
means no hierarchical scheduling, and only one thread per server, |
except for the case of background tasks. |
|
Implementation dependent issue: In order to allow the usage of |
<i> Implementation dependent issue for Marte OS: to allow the usage of |
application defined schedulers, the calling thread must not have |
the SCHED_APP scheduling policy and at the same time be attached to |
an application scheduler different than the fsf scheduler; in such |
case, an error is returned. After a successful call the calling |
thread will have the SCHED_APP scheduling policy and will be |
attached to the fsf scheduler. |
attached to the fsf scheduler.</i> |
|
@param [in] contract pointer to the contract |
@param [out] server id |
703,6 → 672,8 |
|
|
/** |
\ingroup coremodule |
|
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 |
711,10 → 682,10 |
It fails if the server's policy is different than FSF_NONE, or if |
there is already a thread bound to this server |
|
Implementation dependent issue: In order to allow the usage of |
<i> Implementation dependent issue for MARTE OS: In order to allow the usage of |
application defined schedulers, the given thread must not have the |
scheduling policy SCHED_APP and at the same time be attached to an |
application scheduler different than the fsf scheduler. |
application scheduler different than the fsf scheduler. </i> |
|
@param [in] server id |
@param [in] thread id |
723,7 → 694,7 |
of the FSF main scheduler |
@retval 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 |
@retval FSF_ERR_BAD_ARGUMENT if the server value does not comply 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 |
740,12 → 711,14 |
|
|
/** |
\ingroup coremodule |
|
This operation unbinds a thread from a server. Since threads with |
no server associated are not allow to execute, they remain in a |
no server associated are not allowed to execute, they remain in a |
dormant state until they are either eliminated or bound again. |
|
If the thread is inside a critical section the effects of this call |
are deferred until the critical section is ended |
are deferred until the critical section is ended. |
|
Implementation dependent issue: in the implementation with an |
application scheduler, the thread is still attached to the fsf |
768,6 → 741,8 |
fsf_unbind_thread_from_server (pthread_t thread); |
|
/** |
\ingroup coremodule |
|
This operation stores the Id of the server associated with the |
specified thread in the variable pointed to by server. It returns |
an error if the thread does not exist, it is not under the control |
813,6 → 788,8 |
fsf_contract_parameters_t *contract); |
|
/** |
\ingroup coremodule |
|
The operation eliminates the specified server |
and recalculates all necessary parameters for the contracts |
remaining in the system. This is a potentially blocking operation; |
834,6 → 811,8 |
|
|
/** |
\ingroup coremodule |
|
The operation renegotiates a contract for an existing server. If |
the on-line admission test is enabled it determines whether the |
contract can be admitted or not based on the current contracts |
865,6 → 844,8 |
fsf_server_id_t server); |
|
/** |
\ingroup coremodule |
|
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 |
912,6 → 893,8 |
union sigval sig_value); |
|
/** |
\ingroup coremodule |
|
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 |
942,8 → 925,10 |
|
|
/** |
\ingroup coremodule |
|
This operation analizes the schedulability of the context that |
results from negitiating the contracts specified in the |
results from negotiating 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 |
981,9 → 966,6 |
bool *accepted); |
|
|
/*@}*/ |
|
|
//////////////////////////////////////////////////// |
// OBTAINING INFORMATION FROM THE SCHEDULER |
//////////////////////////////////////////////////// |
992,16 → 974,6 |
/** |
\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. |
*/ |
1009,6 → 981,8 |
fsf_is_admission_test_enabled(); |
|
/** |
\ingroup coremodule |
|
This function stores the current execution time spent by the |
threads bound to the specified server in the variable pointed to by |
cpu_time. |
1034,6 → 1008,8 |
struct timespec *cpu_time); |
|
/** |
\ingroup coremodule |
|
This function stores in the variable pointed to by budget the |
remaining execution-time budget associated with the specified |
server. |
1059,6 → 1035,8 |
|
|
/** |
\ingroup coremodule |
|
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 |
1084,31 → 1062,14 |
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 |
negotiations. Increasing the utilization of this thread makes the |
1126,6 → 1087,13 |
|
The service thread starts with a default budget and period that are |
configurable. |
|
<i> Implementation dependency for MARTE OS: 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.</i> |
|
|
@param [in] budget budget for the service thread |
@param [in] period for the service thread |
1149,7 → 1117,9 |
bool *accepted); |
|
/** |
this function returns in the variables pointed by budget and |
\ingroup coremodule |
|
This function returns in the variables pointed by budget and |
period, respectively, the current budget and period of the service |
thread. |
|
1169,6 → 1139,4 |
(struct timespec *budget, |
struct timespec *period); |
|
/* @} */ |
|
#endif // _FSF_CORE_H_ |