Subversion Repositories shark

Compare Revisions

Ignore whitespace Rev 992 → Rev 993

/shark/trunk/ports/first/fsf_include/fsf_core.h
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_