// -----------------------------------------------------------------------
-// Copyright (C) 2005 Mälardalen University, SWEDEN
+// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+//
+// Universidad de Cantabria, SPAIN
+// University of York, UK
+// Scuola Superiore Sant'Anna, ITALY
+// Kaiserslautern University, GERMANY
+// Univ. Politécnica Valencia, SPAIN
+// Czech Technical University in Prague, CZECH REPUBLIC
+// ENEA SWEDEN
+// Thales Communication S.A. FRANCE
+// Visual Tools S.A. SPAIN
+// Rapita Systems Ltd UK
+// Evidence ITALY
+//
+// See http://www.frescor.org for a link to partners' websites
+//
+// FRESCOR project (FP6/2005/IST/5-034026) is funded
+// in part by the European Union Sixth Framework Programme
+// The European Union is not liable of any use that may be
+// made of this code.
+//
+//
+// based on previous work (FSF) done in the FIRST project
+//
+// Copyright (C) 2005 Mälardalen University, SWEDEN
// Scuola Superiore S.Anna, ITALY
// Universidad de Cantabria, SPAIN
// University of York, UK
//
-// FRSH API web pages: http://marte.unican.es/frsh/docs/
+// FSF API web pages: http://marte.unican.es/fsf/docs
// http://shark.sssup.it/contrib/first/docs/
//
// This file is part of FRSH API
// Public License.
// -----------------------------------------------------------------------
//frsh_implementation_specific.h
-//===================================================
-// FFFFFFIII RRRRR SSTTTTTTT
-// FF IIR RR SS
-// FF IR SS
-// FFFFFF RRRR SSSSST
-// FF FI RRR SS
-// FF II RRR SS
-// FF IIIIIR RS
+//==============================================
+// ******** ******* ******** ** **
+// **///// /**////** **////// /** /**
+// ** /** /** /** /** /**
+// ******* /******* /********* /**********
+// **//// /**///** ////////** /**//////**
+// ** /** //** /** /** /**
+// ** /** //** ******** /** /**
+// // // // //////// // //
//
-// FRSH(FIRST Scheduling Framework)
-//implementation-defined optional functionality
-//================================================
-
-#include "frsh_basic_types.h"
-#include "frsh_core.h"
-
-
+// FRSH(FRescor ScHeduler), pronounced "fresh"
+//==============================================
#ifndef _FRSH_IMPLEMENTATION_SPECIFIC_H_
#define _FRSH_IMPLEMENTATION_SPECIFIC_H_
-#define FRSH_IMPLEMENTATION_SPECIFIC_MODULE_SUPPORTED 1
-
-
-// The operations defined in this module are of optional use. They
-// only work in the fixed priority implementation, and they may be
-// used to enhance the behavior of the applications running under the
-// frsh scheduler.
-
-//// The definition of this type is in frsh_basic_types.h
-//
-//typedef unsigned long frsh_preemption_level_t;
-// // range 1..2**32-1
-
+#include "frsh_implementation_specific_types.h"
+#include "frsh_core.h"
-//frsh_set_contract_preemption_level: The operation updates the
-//specified contract parameters object by setting its preemption level
-//to the specified input parameter.
+#define FRSH_IMPLEMENTATION_SPECIFIC_MODULE_SUPPORTED 1
-int
-frsh_set_contract_preemption_level
- (frsh_contract_parameters_t *contract,
+/**
+ * @file frsh_implementation_specific.h
+ *
+ **/
+
+/**
+ * @defgroup implementationspec Implementation Specific module
+ *
+ * The operations defined in this module are of optional use. The
+ * intention is to provide better tunning options taking advantage of
+ * specific characteristics of the underlaying OS.
+ *
+ *
+ * e.g. being able to manually assign priorities assuming that the OS
+ * uses a fixed priority paradigm).
+ *
+ * @{
+ **/
+
+/**
+ * frsh_contract_set_preemption_level()
+ *
+ * The operation updates the specified contract parameters object by
+ * setting its preemption level to the specified input parameter.
+ *
+ * OBSERVATION: if this value is changed being any contract that
+ * uses the resource already accepted, the system's behavior and
+ * particularly the acceptance tests correctness are not garantee
+ * and probably wrong.
+ *
+ **/
+int frsh_contract_set_preemption_level
+ (frsh_contract_t *contract,
frsh_preemption_level_t preemption_level);
-//frsh_get_contract_preemption_level: The operation obtains from the
-//specified contract parameters object its preemption level and copies
-//it to the place pointed to by the specified input parameter.
-
-int
-frsh_get_contract_preemption_level
- (const frsh_contract_parameters_t *contract,
- frsh_preemption_level_t *preemption_level);
-
-
-//frsh_set_service_thread_preemption_level: this function sets the
-//preemption level of the service thread to 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
-
-int
-frsh_set_service_thread_preemption_level
- (frsh_preemption_level_t preemption_level);
-
-//frsh_get_service_thread_preemption_level: this function stores the
-//current preemption level of the service thread in the variable
-//pointed to by preemption_level
-
-int
-frsh_get_service_thread_preemption_level
- (frsh_preemption_level_t *preemption_level);
-
-
-//frsh_thread_exit: 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
-//to continue to be counted in the number of threads. The
-//frsh_thread_exit operation allows the implementation to delete the
-//thread's information, and then terminate the thread. Therefore, it
-//is recommended to use this function to terminate a thread under frsh.
-
-//This operation shall terminate the calling thread, make the value
-//value_ptr available to any successful join with the terminating
-//thread, and unbind the thread from its associated server. After
-//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.
-
-void
-frsh_thread_exit (void *value_ptr);
-
-
-//frsh_set_shared_obj_preemption_level: The operation updates the
-//specified shared object by setting its preemption level
-//to the specified input parameter.
-//OBSERVATION: if this value is changed being any contract that
-//uses the resource already accepted, the system's behavior and
-//particularly the acceptance tests correctness are not garantee
-//and probably wrong.
-
-int
-frsh_set_shared_obj_preemption_level
- (frsh_shared_obj_handle_t obj_handle,
- frsh_preemption_level_t preemption_level);
-
-
-//frsh_get_shared_obj_preemption_level: The operation obtains from the
-//specified shared object its preemption level and copies
-//it to the place pointed to by the specified input parameter.
-
-int
-frsh_get_shared_obj_preemption_level
- (frsh_shared_obj_handle_t obj_handle,
- frsh_preemption_level_t *preemption_level);
-
+/**
+ * frsh_contract_get_preemption_level()
+ *
+ * The operation obtains from the specified contract parameters object
+ * its preemption level and copies it to the place pointed to by the
+ * specified input parameter.
+ **/
+int frsh_contract_get_preemption_level
+ (const frsh_contract_t *contract,
+ frsh_preemption_level_t *preemption_level);
+
+/**
+ * frsh_service_thread_set_preemption_level()
+ *
+ * This function sets the preemption level of the service thread to
+ * 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.
+ **/
+int frsh_service_thread_set_preemption_level
+ (frsh_preemption_level_t preemption_level);
+
+/**
+ * frsh_service_thread_get_preemption_level()
+ *
+ * This function stores the current preemption level of the service
+ * thread in the variable pointed to by preemption_level
+ **/
+int frsh_service_thread_get_preemption_level
+ (frsh_preemption_level_t *preemption_level);
+
+
+/**
+ * frsh_thread_exit()
+ *
+ * This operation shall terminate the calling thread, make the value
+ * value_ptr available to any successful join with the terminating
+ * thread, and unbind the thread from its associated vres. After
+ * 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
+ * to continue to be counted in the number of threads. The
+ * frsh_thread_exit operation allows the implementation to delete the
+ * thread's information, and then terminate the thread. Therefore, it
+ * is recommended to use this function to terminate a thread under frsh.
+ *
+ * Implementation dependent issue: in the implementation with an
+ * 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.
+ **/
+void frsh_thread_exit (void *value_ptr);
+
+
+/**
+ * frsh_sharedobj_set_preemption_level()
+ *
+ * The operation updates the specified shared object by setting its
+ * preemption level to the specified input parameter.
+ *
+ * OBSERVATION: if this value is changed being any contract that
+ * uses the resource already accepted, the system's behavior and
+ * particularly the acceptance tests correctness are not garantee
+ * and probably wrong.
+ **/
+int frsh_sharedobj_set_preemption_level(frsh_sharedobj_handle_t obj_handle,
+ frsh_preemption_level_t preemption_level);
+
+/**
+ * frsh_sharedobj_get_preemption_level()
+ *
+ * The operation obtains from the specified shared object its
+ * preemption level and copies it to the place pointed to by the
+ * specified input parameter.
+ **/
+int frsh_sharedobj_get_preemption_level(frsh_sharedobj_handle_t obj_handle,
+ frsh_preemption_level_t *preemption_level);
+
+/*@}*/
#endif // _FRSH_IMPLEMENTATION_SPECIFIC_H_
projects / frescor / frsh-include.git / blobdiff