From bea975db4dc83e2855aff6ca12a7b04b006fa63c Mon Sep 17 00:00:00 2001 From: telleriam Date: Wed, 19 Dec 2007 20:37:31 +0000 Subject: [PATCH] Correcting function comments and synchronising .h with .c files git-svn-id: http://www.frescor.org/private/svn/frescor/frsh/trunk/include@973 35b4ef3e-fd22-0410-ab77-dab3279adceb --- frsh_core.h | 59 +++++++++++++++++----------------- frsh_implementation_specific.h | 17 ++++++++-- frsh_shared_objects.h | 4 +-- 3 files changed, 46 insertions(+), 34 deletions(-) diff --git a/frsh_core.h b/frsh_core.h index d9b285a..2278814 100644 --- a/frsh_core.h +++ b/frsh_core.h @@ -152,7 +152,6 @@ int frsh_init(); **/ - /** * frsh_contract_init() * @@ -168,14 +167,14 @@ int frsh_init(); * - period_max => {0,0}; * - budget_max => {0,0}; * - period_min => {0,0}; - * - workload => FRSH_INDETERMINATE + * - workload => FRSH_WT_INDETERMINATE * - d_equals_t => true * - contract_type => FRSH_CT_REGULAR; * - deadline => {0,0}; - * - budget_overrun_sig_notify => 0; (signal number) - * - budget_overrun_sig_value => {0, NULL}; - * - deadline_miss_sig_notify => 0; (signal number) - * - deadline_miss_sig_value => {0, NULL}; + * - budget_overrun_signal => 0; (signal number) + * - budget_overrun_siginfo => {0, NULL}; + * - deadline_miss_signal => 0; (signal number) + * - deadline_miss_siginfo => {0, NULL}; * * - granularity => DEFAULT_GRANULARITY; * - utilization_set; => size = 0 @@ -209,8 +208,8 @@ int frsh_contract_init(frsh_contract_t *contract); * @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 FRSH_BOUNDED, - * FRSH_INDETERMINATE or FRSH_OVERHEAD) + * @param[in] workload the kind of workload (can be FRSH_WT_BOUNDED, + * FRSH_WT_INDETERMINATE or FRSH_OVERHEAD) * @param[in] contract_type can be FRSH_CT_REGULAR, * FRSH_CT_BACKGROUND, FRSH_CT_DUMMY. * @@ -261,7 +260,6 @@ int frsh_contract_get_basic_params * @return 0 if no error \n * FRSH_ERR_BAD_ARGUMENT : if the contract pointer is NULL. **/ - int frsh_contract_set_resource_and_label (frsh_contract_t *contract, const frsh_resource_type_t resource_type, @@ -276,7 +274,7 @@ int frsh_contract_set_resource_and_label * * @return 0 if no error \n * FRSH_ERR_BAD_ARGUMENT : if the contract or the contract_label - pointer is NULL. + * pointer is NULL. **/ int frsh_contract_get_resource_and_label (const frsh_contract_t *contract, @@ -300,28 +298,28 @@ int frsh_contract_get_resource_and_label * this parameter is ignored (the contract value * will be NULL_DEADLINE internally). Otherwise, it * contains the desired deadline value. - * @param [in] budget_overrun_sig_notify contains the number of the signal + * @param [in] budget_overrun_signal contains the number of the signal * that must be raised if the budget of the vres is overrun. * If the value of this parameter is FRSH_NULL_SIGNAL, no signal will * be raised. - * @param [in] budget_overrun_sig_value contains the value that will be + * @param [in] budget_overrun_siginfo contains the value that will be * passed to the signal "catcher" when the signal is raised. - * This parameters is not used if the budget_overrun_sig_notify + * This parameters is not used if the budget_overrun_signal * parameter is set to FRSH_NULL_SIGNAL. - * @param [in] deadline_miss_sig_notify contains the number of the + * @param [in] deadline_miss_signal contains the number of the * signal that must be raised if the deadline of the * vres is missed. If the value of this parameter is * FRSH_NULL_SIGNAL, no signal is raised. - * @param [in] deadline_miss_sig_value contains the value that will be + * @param [in] deadline_miss_siginfo contains the value that will be * passed to the signal "catcher" when the signal is * raised. This parameter is not used if the - * deadline_sig_notify parameter is set to NULL_SIGNAL + * deadline_signal parameter is set to NULL_SIGNAL * * @return 0 if successful\n * FRSH_ERR_BAD_ARGUMENT : if contract is NULL \b or \n * (d_equals_t is true and deadline is not FRSH_NULL_DEADLINE) \b or \n - * (budget_overrun_sig_notify is not a valid signal) \b or \n - * (deadline_miss_sig_notify is not a valid signal) \b or \n + * (budget_overrun_signal is not a valid signal) \b or \n + * (deadline_miss_signal is not a valid signal) \b or \n * (d_equals_t is false but (deadline is FRSH_NULL_DEADLINE or its value * is grater than the contract's maximum period)) * @@ -403,12 +401,13 @@ int frsh_contract_get_timing_reqs * variable managed by the scheduler, and returns a handle to it in * the variable pointed to by synch_handle. * - * @param[out] pointer to the variable that will contain the handle to the - * newly created synchronization object + * @param[out] synch_handle pointer to the variable that will contain + * the handle to the newly created synchronization object + * + * @return 0 if the operation is succesful + * FRSH_ERR_TOO_MANY_SYNCH_OBJS if the number of synchronization + * objects in the system has already exceeded the maximum * - * @return 0 if no error \n - * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0\n - * . * FRSH_ERR_TOO_MANY_SYNCH_OBJS : if the number of synchronization * objects in the system has already exceeded the maximum\n * . @@ -426,10 +425,10 @@ int frsh_synchobj_create * frsh_synchobj_destroy() * * This operation destroys the synchronization object (created by a - * previous call to frsh_create_synch_obj) that is referenced by the + * previous call to frsh_synchobj_create) that is referenced by the * synch_handle variable. After calling this operation, the * synch_handle variable can not be used until it is initialized again - * by a call to frsh_create_synch_obj. + * by a call to frsh_synchobj_create. * * @param synch_handle the handle to the synchronization object * to be destroyed @@ -531,7 +530,7 @@ int frsh_synchobj_wait /** * frsh_synchobj_wait_with_timeout() * -g * This call is the same as frsh_synchobj_wait() but with an extra + * This call is the same as frsh_synchobj_wait() but with an extra * absolute timeout. The timed_out argument, indicates whether the * function returned because of the expiration of the timeout or not. * @@ -615,7 +614,7 @@ int frsh_synchobj_signal * mentioned abobe, only when the call finishes the budget may be * replenished. * - * * @param [in] abs_time absolute time at which the budget will be + * @param [in] abs_time absolute time at which the budget will be * replenished * * @param [out] next_budget upon return of this function, the variable @@ -1073,7 +1072,7 @@ int frsh_contract_renegotiate_async * * If the vres is not and has not been involved in any of the * frsh_contract_renegotiate_async() or frsh_group_change_mode_async() - * operations, the status returned is FRSH_NOT_REQUESTED + * operations, the status returned is FRSH_RS_NOT_REQUESTED * * @return 0 if no error \n * FRSH_ERR_BAD_ARGUMENT : if the renegotiation_status argument is @@ -1159,7 +1158,7 @@ int frsh_group_negotiate /** * frsh_group_change_mode_sync() * - * An extension of frsh_negotiate_group() by adding the possibility of + * An extension of frsh_group_negotiate() by adding the possibility of * specifying also group contract renegotiation and removal. * * NOTE: This function will be implemented in a second phase after @@ -1232,7 +1231,7 @@ int frsh_group_change_mode_sync * as it is practical. * * NOTE: This function will be implemented in a second phase after - * having fully implemented frsh_negotiate_group() in order to + * having fully implemented frsh_group_negotiate() in order to * better grasp possible issues that the problem may raise. * * This is a draft of the specification, it is yet subject to diff --git a/frsh_implementation_specific.h b/frsh_implementation_specific.h index 43f7d8e..3ba3009 100644 --- a/frsh_implementation_specific.h +++ b/frsh_implementation_specific.h @@ -130,7 +130,7 @@ int frsh_contract_get_preemption_level * the specified value. The initial preemption level is a configurable * parameter. This value is stored in a temporary variable and it is * used the next time the service thread data is updated with the - * frsh_set_service_thread_data() function. + * frsh_service_thread_set_data() function. **/ int frsh_service_thread_set_preemption_level (frsh_preemption_level_t preemption_level); @@ -154,7 +154,7 @@ int frsh_service_thread_get_preemption_level * cleaning up the thread management data, it is unbound and the * scheduling policy is changed to fixed priority before the posix * pthread_exit() function is called. - * + * * There is a limitation in the current version of the * MaRTE implementation that causes the information of a terminated * thread to continue to be stored in the frsh scheduler, and the thread @@ -167,6 +167,19 @@ int frsh_service_thread_get_preemption_level * application scheduler, after cleaning up the thread management * data, it is unbound and the scheduling policy changed to fixed * priority before calling the posix pthread_exit() function. + * + * NOTE: This function, together with the internal function + * frsh_internal_remove_thread() has been removed from FRSH + * because it shouldn't be necessary. + * + * If there are some problems with MaRTE in thread termination + * it should be fixed in the OS and not here. + * + * The function does not do anything special that is not done in the + * terminate callback of the FRSH scheduler. + * + * If you want to be curious about what the function did, look at the + * SVN repository (revision 273) or one of the past branches. **/ void frsh_thread_exit (void *value_ptr); diff --git a/frsh_shared_objects.h b/frsh_shared_objects.h index c212074..5e9e168 100644 --- a/frsh_shared_objects.h +++ b/frsh_shared_objects.h @@ -478,7 +478,7 @@ int frsh_csect_register_write_op * frsh_csect_get_op_kind() * * Returns the type of operation (read/write/unchecked) of the critical section. - + * * @return 0 if no error \n * FRSH_ERR_BAD_ARGUMENT : if csect or op_kind are NULL or csect * is not correct \n @@ -647,7 +647,7 @@ int frsh_csect_get_blocking_time * @return 0 if no error \n * FRSH_ERR_BAD_ARGUMENT : if any of the pointers is NULL or * the size of the critical_sections structure is less than zero - * or grater than FRSH_MAX_N_CRITICAL_SECTIONS + * or greater than FRSH_MAX_N_CRITICAL_SECTIONS * **/ int frsh_contract_set_csects -- 2.39.2