From: telleriam Date: Mon, 19 Feb 2007 19:04:04 +0000 (+0000) Subject: Renaming FOSA ADS function to use _ to separate words. X-Git-Url: https://rtime.felk.cvut.cz/gitweb/frescor/fosa.git/commitdiff_plain/090286e3157d2b3bcaea212903686f4b85427616 Renaming FOSA ADS function to use _ to separate words. Some corrections in the doxygen documentation. git-svn-id: http://www.frescor.org/private/svn/frescor/fosa/trunk@309 35b4ef3e-fd22-0410-ab77-dab3279adceb --- diff --git a/doc/api_html.tar.gz b/doc/api_html.tar.gz index f0e910e..ca63d28 100644 Binary files a/doc/api_html.tar.gz and b/doc/api_html.tar.gz differ diff --git a/doc/fosa_api.pdf b/doc/fosa_api.pdf index 3380443..addc9bb 100644 Binary files a/doc/fosa_api.pdf and b/doc/fosa_api.pdf differ diff --git a/include/fosa.h b/include/fosa.h index 6a7540f..27c03ab 100644 --- a/include/fosa.h +++ b/include/fosa.h @@ -74,4 +74,40 @@ #include "fosa_app_def_sched.h" +/** + * @defgroup fosa FOSA Private Interfaces + * + * FOSA is an OS adaption layer that encapsulates all POSIX types and + * functions into neutral names so that FRSH can compile and be used in + * non-POSIX operating systems such as OSE. + * + * It is divided in two parts: + * - FRSH_FOSA: Types visible to the application via FRSH_API and + * the functions to manage them (thread, signals). + * - FOSA: Types and functions only used within FRSH. + * + * The former reside in the FRSH subversion directory and the latter + * have their own. They need to be separated because the application + * must not see FOSA itself. + * + * For simplicity, we have chosen to hide the operation function on + * signals and mutexes with the assumption that a direct mapping + * exists for frsh_signal_t, frsh_signal_info_t and frsh_mutext_t in + * the native OS. + * + * Since there are some parts which are platform dependent a define + * has been introduced for each platform. Currently the supported + * defines are: + * + * -DRT_LINUX + * -DOSE + * -DMARTE_OS + * + * This module contains all other modules that are internal to the + * FRSH implementation. + * + * Note that to compile FOSA objects an include path towards FRSH is + * needed: -I. + **/ + #endif // _FOSA_H_ diff --git a/include/fosa_app_def_sched.h b/include/fosa_app_def_sched.h index 6be4a1e..02809bb 100644 --- a/include/fosa_app_def_sched.h +++ b/include/fosa_app_def_sched.h @@ -64,6 +64,7 @@ /** * @defgroup appdefsched Application Defined Scheduling + * @ingroup fosa * * This module defines the function and types for an abstraction of * the Application Defined Scheduling. @@ -126,7 +127,7 @@ int fosa_ads_scheduler_create size_t init_args_size); /** - * fosa_thread_attr_setappscheduled() + * fosa_thread_attr_set_appscheduled() * * Set the appscheduled attribute of a thread attributes object * @@ -143,12 +144,12 @@ int fosa_ads_scheduler_create * notify it to the system console and then terminate the FRSH * implementation and dependant applications **/ -int fosa_thread_attr_setappscheduled +int fosa_thread_attr_set_appscheduled (frsh_thread_attr_t *attr, bool appscheduled); /** - * fosa_thread_attr_getappscheduled() + * fosa_thread_attr_get_appscheduled() * * Get the appscheduled attribute of a thread attributes object * @@ -165,12 +166,12 @@ int fosa_thread_attr_setappscheduled * notify it to the system console and then terminate the FRSH * implementation and dependant applications **/ -int fosa_thread_attr_getappscheduled +int fosa_thread_attr_get_appscheduled (const frsh_thread_attr_t *attr, bool *appscheduled); /** - * fosa_thread_attr_setappschedparam() + * fosa_thread_attr_set_appsched_params() * * Set the appsched_param attribute of a thread attributes object * @@ -190,13 +191,13 @@ int fosa_thread_attr_getappscheduled * notify it to the system console and then terminate the FRSH * implementation and dependant applications **/ -int fosa_thread_attr_setappschedparam +int fosa_thread_attr_set_appsched_params (frsh_thread_attr_t *attr, const void *param, size_t paramsize); /** - * fosa_thread_attr_getappschedparam() + * fosa_thread_attr_get_appsched_params() * * Get the appsched_param attribute of a thread attributes object * @@ -217,13 +218,13 @@ int fosa_thread_attr_setappschedparam * notify it to the system console and then terminate the FRSH * implementation and dependant applications **/ -int fosa_thread_attr_getappschedparam +int fosa_thread_attr_get_appsched_params (const frsh_thread_attr_t *attr, void *param, size_t *paramsize); /** - * fosa_ads_setappscheduled() + * fosa_ads_set_appscheduled() * * Dynamically set the appscheduled attribute of a thread * @@ -245,7 +246,7 @@ int fosa_thread_attr_getappschedparam * notify it to the system console and then terminate the FRSH * implementation and dependant applications **/ -int fosa_ads_setappscheduled +int fosa_ads_set_appscheduled (frsh_thread_id_t thread, bool appscheduled); @@ -267,7 +268,7 @@ int fosa_ads_setappscheduled * notify it to the system console and then terminate the FRSH * implementation and dependant applications **/ -int fosa_ads_getappscheduled +int fosa_ads_get_appscheduled (frsh_thread_id_t thread, bool *appscheduled); @@ -294,13 +295,13 @@ int fosa_ads_getappscheduled * notify it to the system console and then terminate the FRSH * implementation and dependant applications **/ -int fosa_ads_setappschedparam +int fosa_ads_set_appschedparam (frsh_thread_id_t thread, const void *param, size_t paramsize); /** - * fosa_ads_getappschedparam() + * fosa_ads_get_appsched_params() * * Dynamically get the appsched_param attribute of a thread * @@ -322,7 +323,7 @@ int fosa_ads_setappschedparam * notify it to the system console and then terminate the FRSH * implementation and dependant applications. **/ -int fosa_ads_getappschedparam +int fosa_ads_get_appsched_params (frsh_thread_id_t thread, void *param, size_t *paramsize); @@ -339,7 +340,7 @@ int fosa_ads_getappschedparam *********************************/ /** - * fosa_adsactions_addreject() + * fosa_adsactions_add_reject() * * Add a reject-thread action * @@ -351,11 +352,11 @@ int fosa_ads_getappschedparam * resources for the new thread. At the end of the new_thread() * scheduler primitive operation, the parent of the rejected thread * waiting on a fosa_thread_create() or the rejected thread itself - * waiting on a fosa_ads_setappscheduled() function shall complete the + * waiting on a fosa_ads_set_appscheduled() function shall complete the * function with an error code of EREJECT. If no reject-thread action * is added during the new_thread() scheduler primitive operation, the * thread is accepted to be scheduled by the scheduler and the - * associated fosa_thread_create() or the fosa_ads_setappscheduled() + * associated fosa_thread_create() or the fosa_ads_set_appscheduled() * function shall be completed without error. For the function to * succeed, it has to be called from the new_thread() primitive * operation and for the thread that is requesting attachment to the diff --git a/include/fosa_clocks_and_timers.h b/include/fosa_clocks_and_timers.h index 7a0ed88..fd71798 100644 --- a/include/fosa_clocks_and_timers.h +++ b/include/fosa_clocks_and_timers.h @@ -64,6 +64,7 @@ /** * @defgroup clocksandtimers Clocks and Timers + * @ingroup fosa * * This module defines the types and functions to abstract clocks and * timers for the FRSH implementation. diff --git a/include/fosa_errors.h b/include/fosa_errors.h index a0ec801..e020fad 100644 --- a/include/fosa_errors.h +++ b/include/fosa_errors.h @@ -63,6 +63,7 @@ /** * @defgroup fosaerror FOSA Errors + * @ingroup fosa * * We define return error values. * diff --git a/include/fosa_mutexes_and_condvars.h b/include/fosa_mutexes_and_condvars.h index 3a72980..c53e51a 100644 --- a/include/fosa_mutexes_and_condvars.h +++ b/include/fosa_mutexes_and_condvars.h @@ -63,6 +63,7 @@ /** * @defgroup mutexesandcondvars Mutexes and Condvars + * @ingroup fosa * * This module defines the types and functions to abstract mutexes and * conditional variables for the FRSH implementation. diff --git a/include/fosa_threads_and_signals.h b/include/fosa_threads_and_signals.h index c8b60ee..7dde51f 100644 --- a/include/fosa_threads_and_signals.h +++ b/include/fosa_threads_and_signals.h @@ -64,6 +64,7 @@ /** * @defgroup threadandsignals Thread and Signals + * @ingroup fosa * * This module defines the functions that manipulate frsh_threads and * frsh_signals inside FRSH implementation. @@ -72,8 +73,8 @@ * directly, instead they must use frsh_thread_create*() which in turn * use fosa_thread_create(). * - * For signals, application threads cannot signal them but only wait - * on them. + * For signals, we assume that the OS provides a direct mapping + * for frsh_signal_t and frsh_signal_info_t in the native interface. * * @{ **/ diff --git a/include/fosa_types.h b/include/fosa_types.h index 3b8a31e..442f88f 100644 --- a/include/fosa_types.h +++ b/include/fosa_types.h @@ -138,44 +138,53 @@ typedef int fosa_ads_urgency_t; * contains pointers to the primitive operations that are invoked by * the system when a scheduling event occurs: * - * - The init() primitive operation is invoked by the system just after + * - The \b init() primitive operation is invoked by the system just after * the scheduler has been created using fosa_ads_scheduler_create(). * - * - The new_thread() primitive operation is invoked by the system when + * - The \b new_thread() primitive operation is invoked by the system when * a thread has requested attachment to this scheduler; this can be a * newly created thread (via fosa_thread_create()), or an existing thread * that was not running under ads scheduler (via - * fosa_ads_setappscheduled()). The thread can be rejected by the - * scheduler adding a reject-thread action to the actions parameter - * using fosa_ads_actions_addreject(). If no reject-thread - * action is added, the thread is accepted. Newly created threads - * shall be activated by the system after the execution of the - * new_thread() primitive operation. The urgency of an accepted thread - * (either newly created or existing) shall be set to a value of zero, - * unless an activate-thread action with a different value of urgency - * is added via fosa_ads_actions_addactivate(). If a request to - * attach a thread to this scheduler was made via - * fosa_ads_setappscheduled(), at the finalization of the new_thread() + * fosa_ads_set_appscheduled()).\n \n + * . + * The thread can be rejected by the scheduler adding a + * reject-thread action to the actions parameter using + * fosa_ads_actions_add_reject(). If no reject-thread action is + * added, the thread is accepted.\n \n + * . + * Newly created threads shall be activated by the system after the + * execution of the new_thread() primitive operation. The urgency of + * an accepted thread (either newly created or existing) shall be set + * to a value of zero, unless an activate-thread action with a + * different value of urgency is added via + * fosa_ads_actions_add_activate().\n \n + * . + * If a request to attach a thread to this scheduler was made via + * fosa_ads_set_appscheduled(), at the finalization of the new_thread() * primitive operation if the newly attached thread is blocked by the - * system (not by the scheduler itself via a ’¡Èsuspend’¡É scheduling + * system (not by the scheduler itself via a suspend scheduling * action), a thread-block event shall be generated for the scheduler * immediately and, consequently, the thread_block() primitive * operation shall be invoked by the system. * - * - The thread_terminate() primitive operation is invoked by the system + * - The \b thread_terminate() primitive operation is invoked by the system * when a thread attached to this scheduler is terminating (via an * explicit or implicit thread termination, or cancellation, or when * it is no longer sceduled by the ads scheduler (via - * fosa_ads_setappscheduled()). Before the thread_terminate() - * primitive operation is invoked by the system, all the - * thread-notification events programmed for that thread are - * cancelled. In the case of a thread that is terminating the + * fosa_ads_setappscheduled()). \n\n + * . + * Before the thread_terminate() primitive operation is invoked by + * the system, all the thread-notification events programmed for that + * thread are cancelled. \n\n + * . + * In the case of a thread that is terminating, the * thread_terminate() primitive operation is executed before the * execution of the cleanup handlers and of the thread-specific data * destructor functions. In that way, the thread parameter corresponds * to a valid thread Id and the thread-specific data is valid and can - * be accessed from the thread_terminate() primitive operation. Also - * for terminating threads, after the thread_terminate() primitive + * be accessed from the thread_terminate() primitive operation. \n\n + * . + * Also for terminating threads, after the thread_terminate() primitive * operation finishes, the system shall lower the urgency of the * thread identified by thread to a value of zero, and shall deattach * it from the ads scheduler. Then, the thread shall execute the @@ -185,47 +194,50 @@ typedef int fosa_ads_urgency_t; * identified by parameter thread during the execution of the * thread_terminate() primitive operation. * - * - The thread_ready() primitive operation is invoked by the system + * - The \b thread_ready() primitive operation is invoked by the system * when a thread attached to this scheduler that was blocked has * become unblocked by the system. * - * - The thread_block() primitive operation is invoked by the system + * - The \b thread_block() primitive operation is invoked by the system * when a thread attached to this scheduler has blocked. * - * - The change_sched_param_thread() primitive operation is invoked by + * - The \b change_sched_param_thread() primitive operation is invoked by * the system when the scheduling parameters of a thread attached to * this scheduler have been changed, but the thread continues to run - * under this scheduler. The change includes either the regular sched- - * uling parameters (fosa_thread_set_prio() or the application-defined - * scheduling parameters, via fosa_ads_setappschedparam(). + * under this scheduler. The change includes either the regular + * scheduling parameters (fosa_thread_set_prio() or the application- + * defined scheduling parameters, via fosa_ads_set_appsched_param(). * - * - The explicit_call_with_data() primitive operation is invoked by the + * - The \b explicit_call_with_data() primitive operation is invoked by the * system when a thread (identified by the thread parameter) has * explicitly invoked the scheduler with a message containing * scheduling information, and possibly requesting a reply message, * via fosa_ads_invoke_withdata(). * - * - The notification_for_thread() primitive operation is invoked by the + * - The \b notification_for_thread() primitive operation is invoked by the * system when the time for a thread-notification previously programed - * by the scheduler via fosa_ads_actions_addthreadnotification() + * by the scheduler via fosa_ads_actions_add_thread_notification() * is reached. Parameter clock identifies the clock for which the * thread-notification was programmed. * - * - The timeout() primitive operation is invoked by the system when a + * - The \b timeout() primitive operation is invoked by the system when a * timeout requested by the scheduler (via - * fosa_ads_actions_addtimeout()) has expired. + * fosa_ads_actions_add_timeout()) has expired. * - * - The signal() primitive operation is invoked by the system when a + * - The \b signal() primitive operation is invoked by the system when a * signal belonging to the set of signals for which the scheduler is - * waiting (via fosa_ads_sethandledsignalset()) has been - * generated. The signal number and its associated information (if - * any) are passed in the arguments signal and siginfo. The signal is - * consumed with the invocation of this primitive operation, which - * implies that it will not cause the execution of any signal handler, - * nor it may be accepted by any thread waiting for this signal - * number. + * waiting (via fosa_ads_set_handled_signal_set()) has been + * generated. \n\n + * . + * The signal number and its associated information (if any) are + * passed in the arguments signal and siginfo.\n\n + * . + * The signal is consumed with the invocation of this primitive + * operation, which implies that it will not cause the execution of + * any signal handler, nor it may be accepted by any thread waiting + * for this signal number. * - * - The appsched_error() primitive operation is invoked by the system + * - The \b appsched_error() primitive operation is invoked by the system * when an error in the scheduling actions list specified in a * previous primitive operation is detected. The cause of the error is * notified in the parameter cause. The defined causes of error are