diff options
Diffstat (limited to 'runtime')
28 files changed, 1028 insertions, 140 deletions
diff --git a/runtime/org.eclipse.etrice.runtime.c/run_doxygen_runtime.c.launch b/runtime/org.eclipse.etrice.runtime.c/run_doxygen_runtime.c.launch new file mode 100644 index 000000000..63be04afa --- /dev/null +++ b/runtime/org.eclipse.etrice.runtime.c/run_doxygen_runtime.c.launch @@ -0,0 +1,6 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<launchConfiguration type="org.eclipse.ui.externaltools.ProgramLaunchConfigurationType"> +<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="C:\cygwin\bin\doxygen.exe"/> +<stringAttribute key="org.eclipse.ui.externaltools.ATTR_TOOL_ARGUMENTS" value="org.eclipse.etrice.runtime.c.doxyfile"/> +<stringAttribute key="org.eclipse.ui.externaltools.ATTR_WORKING_DIRECTORY" value="${workspace_loc:/org.eclipse.etrice.runtime.c}"/> +</launchConfiguration> diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory.h b/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory.h index a0baa20ff..38d274e5a 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory.h @@ -15,6 +15,10 @@ #include "etDatatypes.h" +/** + * this macro computes the memory aligned value for a given size. It uses the ALIGNMENT + * defined in etDatatypes.h + */ #define MEM_CEIL(n) ((n)+((ALIGNMENT-((n)&(ALIGNMENT-1)))&(ALIGNMENT-1))) struct etMemory; @@ -40,7 +44,9 @@ typedef struct etMemory { /** size of the heap in bytes */ etUInt32 size; + /** the configured allocation method */ etMemory_alloc* alloc; + /** the configured freeing method */ etMemory_free* free; } etMemory; diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FixedSize.h b/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FixedSize.h index 1a8715f0d..855f3e53f 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FixedSize.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FixedSize.h @@ -10,6 +10,14 @@ * *******************************************************************************/ +/** + * \file etMemory_FixedSize.h + * + * a simple memory management that uses equal sized chunks. The free chunks are maintained in + * a \ref etQueue + * + * \author Thomas Schuetz, Henrik Rentz-Reichert + */ #ifndef _ETMEMORY_FIXED_SIZE_H_ #define _ETMEMORY_FIXED_SIZE_H_ diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FreeList.c b/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FreeList.c index 2421932fb..ac9f5e29e 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FreeList.c +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FreeList.c @@ -22,29 +22,20 @@ typedef struct etFreeListObj { } etFreeListObj; typedef struct etFreeListInfo { - /** the size in bytes of the objects in this list */ - etUInt16 objsize; - - /** the list head */ - etFreeListObj* head; + etUInt16 objsize; /**< the size in bytes of the objects in this list */ + etFreeListObj* head; /**< the list head */ #if DEBUG_FREE_LISTS - etUInt16 nobjects; + etUInt16 nobjects; /**< the number of objects in the list */ #endif } etFreeListInfo; typedef struct etFreeListMemory { - etMemory base; - - /** next free position on the heap */ - etUInt8* current; - - /** number of free lists */ - etUInt16 nslots; - - /** array of free list infos (array used with size nslots) */ - etFreeListInfo freelists[1]; + etMemory base; /** the "base class" */ + etUInt8* current; /**< next free position on the heap */ + etUInt16 nslots; /**< number of free lists */ + etFreeListInfo freelists[1]; /**< array of free list infos (array used with size nslots) */ } etFreeListMemory; /* diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FreeList.h b/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FreeList.h index b5842d523..ff2806593 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FreeList.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FreeList.h @@ -13,6 +13,13 @@ #ifndef _ETMEMORY_FREE_LIST_H_ #define _ETMEMORY_FREE_LIST_H_ +/** + * \file etMemory_FreeList.h + * + * a heap management that recycles freed objects in slots of objects of equal size + * + * \author Henrik Rentz-Reichert + */ #include "base/etMemory.h" /** @@ -24,12 +31,45 @@ * * \return the pointer to the initialized etMemory struct */ - etMemory* etMemory_FreeList_init(void* heap, etUInt32 size, etUInt16 nslots); +/** + * determines and returns the free memory of the heap + * + * \param heap pointer to the heap to be managed + * + * \return the free memory of the heap + */ etUInt32 etMemory_FreeList_freeHeapMem(void* heap); + +/** + * returns the number of objects in a given slot + * + * \param heap pointer to the heap to be managed + * \param slot the slot number + * + * \return the number of objects in a given slot or <code>0</code> if invalid slot + * or <code>DEBUG_FREE_LISTS</code> isn't <code>true</code> + */ etUInt16 etMemory_FreeList_nObjects(void* heap, etUInt16 slot); + +/** + * returns the size of the objects in a given slot + * + * \param heap pointer to the heap to be managed + * \param slot the slot number + * + * \return the size of the objects in a given slot + */ etUInt16 etMemory_FreeList_sizeObjects(void* heap, etUInt16 slot); + +/** + * returns the number of free slots + * + * \param heap pointer to the heap to be managed + * + * \return the number of free slots + */ etUInt16 etMemory_FreeList_freeSlots(void* heap); #endif /* _ETMEMORY_FREE_LIST_H_ */ diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etDataLogger.h b/runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etDataLogger.h index f78594bc1..1985703f2 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etDataLogger.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etDataLogger.h @@ -10,18 +10,58 @@ * *******************************************************************************/ +/** + * \file etDataLogger.h + * + * The data logger is a means that lets data driven send ports write their data to file + * in every cycle. Only one log file can be open at a time. The data are written + * in comma separated value (csv) format. + * + * \author Henrik Rentz-Reichert + */ + #ifndef ETDATALOGGER_H_ #define ETDATALOGGER_H_ #include "etRuntimeConfig.h" +/** + * opens a file for data logging + * + * \param logPath the path to the file + * \param logName the name of the log file + */ void etDataLogger_open(const char* logPath, const char* logName); +/** + * closes a previously opened data log file + */ void etDataLogger_close(void); +/** + * writes a string to the log + * + * \param text the string to be written + */ void etDataLogger_logString(const char* text); +/** + * writes a boolean value to the log (as integer) + * + * \param val the value to be written + */ void etDataLogger_logBool(int val); +/** + * writes an integer value to the log + * \param val the value to be written + */ void etDataLogger_logInt(int val); +/** + * writes a double value to the log + * \param val the value to be written + */ void etDataLogger_logDouble(double val); +/** + * starts a new row of the log + */ void etDataLogger_newRow(); #ifdef ET_DATA_LOGGER_ACTIVATE @@ -40,12 +80,48 @@ void etDataLogger_newRow(); #define ET_DATA_LOGGER_NEW_ROW \ etDataLogger_newRow(); #else + /** + * calls \ref etDataLogger_open(const char*, const char*) with path <code>tmp/log</code> + * or <code>void</code> if <code>ET_DATA_LOGGER_ACTIVATE</code> is not defined + */ #define ET_DATA_LOGGER_OPEN(name) + /** + * calls \ref etDataLogger_close() + * or <code>void</code> if <code>ET_DATA_LOGGER_ACTIVATE</code> is not defined + */ #define ET_DATA_LOGGER_CLOSE + /** + * calls etDataLogger_logString(const char*) + * or <code>void</code> if <code>ET_DATA_LOGGER_ACTIVATE</code> is not defined + * + * \param text the text to be written + */ #define ET_DATA_LOGGER_LOG_STRING(text) + /** + * calls \ref etDataLogger_logBool(int val) + * or <code>void</code> if <code>ET_DATA_LOGGER_ACTIVATE</code> is not defined + * + * \param val the value to be written + */ #define ET_DATA_LOGGER_LOG_BOOL(val) + /** + * calls \ref etDataLogger_logInt(int val) + * or <code>void</code> if <code>ET_DATA_LOGGER_ACTIVATE</code> is not defined + * + * \param val the value to be written + */ #define ET_DATA_LOGGER_LOG_INT(val) + /** + * calls \ref etDataLogger_logDouble(double val) + * or <code>void</code> if <code>ET_DATA_LOGGER_ACTIVATE</code> is not defined + * + * \param val the value to be written + */ #define ET_DATA_LOGGER_LOG_DOUBLE(val) + /** + * calls \ref etDataLogger_newRow() + * or <code>void</code> if <code>ET_DATA_LOGGER_ACTIVATE</code> is not defined + */ #define ET_DATA_LOGGER_NEW_ROW #endif diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etLogger.h b/runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etLogger.h index b353e6f1a..2c9c386bf 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etLogger.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etLogger.h @@ -10,11 +10,12 @@ * *******************************************************************************/ -/* - * etLogger.h +/** + * \file etLogger.h * - * Created on: 16.01.2012 - * Author: tschuetz + * a simple logging facility writing to file + * + * \author: tschuetz */ #ifndef _ETLOGGER_H_ @@ -22,27 +23,73 @@ #include <stdio.h> #include "etDatatypes.h" -/* logging */ +/** + * open a log file + * + * \param filename the file name + * \param mode the read/write mode (see standard C fopen) + * + * \return a file handle (OS specific) + */ +etFileHandle etLogger_fopen(const char* filename, const char* mode); + +/** + * close a log file + * + * \param file the file handle + * + * \return <code>0</code> if ok + */ +int etLogger_fclose(etFileHandle file); + +/** + * log an error + * + * \param message the message to write + */ void etLogger_logError(const char* message); +/** + * log a warning + * + * \param message the message to write + */ void etLogger_logWarning(const char* message); +/** + * log an information + * + * \param message the message to write + */ void etLogger_logInfo(const char* message); +/** + * log an error + * + * \param format the format to be used (see standard C printf) + */ void etLogger_logErrorF(const char* format, ... ); +/** + * log a warning + * + * \param format the format to be used (see standard C printf) + */ void etLogger_logWarningF(const char* format, ... ); +/** + * log an information + * + * \param format the format to be used (see standard C printf) + */ void etLogger_logInfoF(const char* format, ... ); - -/* File handling */ - -etFileHandle etLogger_fopen(const char* filename, const char* mode); - -int etLogger_fclose(etFileHandle file); - +/** + * log a string in free format + * + * \param format the format to be used (see standard C printf) + */ void etLogger_fprintf(etFileHandle file, const char* format, ... ); #endif /* _ETLOGGER_H_ */ diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etMSCLogger.h b/runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etMSCLogger.h index dcef23aeb..243b28f97 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etMSCLogger.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etMSCLogger.h @@ -10,23 +10,84 @@ * *******************************************************************************/ +/** + * \file etMSCLogger.h + * + * A collection of methods that can be used to write a message sequence chart (MSC, + * also called sequence diagram in UML). + * The format used is compatible with Astade Trace2UML, an open source MSC viewer. + * + * \author Thomas Schuetz + */ #ifndef _ETMSCLOGGER_H_ #define _ETMSCLOGGER_H_ #include "etRuntimeConfig.h" +/** + * opens a log file for the MSC. Only one at a time can be open. + * + * \param logPath the file path + * \param mscName the file name + */ void etMSCLogger_open(const char* logPath, const char* mscName); +/** + * closes the MSC + */ void etMSCLogger_close(void); +/** + * sets an object name (for internal use) + * + * \param objectName the object name + */ void etMSCLogger_setObjectName(const char* objectName); +/** + * returns the object name previously set + * + * \return the object name + */ const char* etMSCLogger_getObjectName(void); +/** + * logs a synchronous call + * + * \param sourceName the calling instance + * \param messageName the message + * \param targetName the called instance + */ void etMSCLogger_syncCall(const char* sourceName, const char* messageName, const char* targetName); +/** + * logs a synchronous return + * + * \param sourceName the calling instance + * \param targetName the called instance + */ void etMSCLogger_syncReturn(const char* sourceName, const char* targetName); +/** + * logs an outgoing asynchronous message + * + * \param sourceName the calling instance + * \param messageName the message + * \param targetName the called instance + */ void etMSCLogger_asyncOut(const char* sourceName, const char* messageName, const char* targetName); +/** + * logs an incoming asynchronous message + * + * \param sourceName the calling instance + * \param messageName the message + * \param targetName the called instance + */ void etMSCLogger_asyncIn(const char* sourceName, const char* messageName, const char* targetName); +/** + * logs a state change + * + * \param objectName the stateful instance + * \param stateName the new state + */ void etMSCLogger_setState(const char* objectName, const char* stateName); #ifdef ET_MSC_LOGGER_ACTIVATE @@ -67,16 +128,65 @@ void etMSCLogger_setState(const char* objectName, const char* stateName); #else - #define ET_MSC_LOGGER_OPEN - #define ET_MSC_LOGGER_CLOSE - #define ET_MSC_LOGGER_SYNC_ENTRY(object, message) - #define ET_MSC_LOGGER_SYNC_EXIT - - #define ET_MSC_LOGGER_ASYNC_OUT(sourceName, message, targetName) - #define ET_MSC_LOGGER_ASYNC_IN(sourceName, message, targetName) - - #define ET_MSC_LOGGER_CHANGE_STATE(objectName, stateName) +/** + * calls \ref etMSCLogger_open(const char*, const char*) with <code>tmp/log</code> as path + * and <code>msc</code> as file name for the log. Then it calls \ref etMSCLogger_setObjectName(const char*) + * with object. + * \par + * If \ref ET_MSC_LOGGER_ACTIVATE isn't defined this macro is void + * + * \param object the object name to be set + */ +#define ET_MSC_LOGGER_OPEN(object) + +/** + * calls \ref etMSCLogger_close() + * \par + * If \ref ET_MSC_LOGGER_ACTIVATE isn't defined this macro is void + */ +#define ET_MSC_LOGGER_CLOSE + +/** + * this macro has to be used together with \ref ET_MSC_LOGGER_SYNC_EXIT to log + * method entry and exit. It declares local variables and calls \ref etMSCLogger_syncCall + * \par + * If \ref ET_MSC_LOGGER_ACTIVATE or \ref ET_SYNC_MSC_LOGGER_ACTIVATE + * aren't defined this macro is void + */ +#define ET_MSC_LOGGER_SYNC_ENTRY(object, message) +/** + * this macro has to be used together with \ref ET_MSC_LOGGER_SYNC_ENTRY to log + * method entry and exit. It uses local variables defined before by \ref ET_MSC_LOGGER_SYNC_ENTRY and + * calls \ref etMSCLogger_syncCall + * \par + * If \ref ET_MSC_LOGGER_ACTIVATE or \ref ET_SYNC_MSC_LOGGER_ACTIVATE + * aren't defined this macro is void + */ +#define ET_MSC_LOGGER_SYNC_EXIT + +/** + * calls \ref etMSCLogger_asyncOut(const char*, const char*, const char*) + * \par + * If \ref ET_MSC_LOGGER_ACTIVATE or \ref ET_ASYNC_MSC_LOGGER_ACTIVATE + * aren't defined this macro is void + */ +#define ET_MSC_LOGGER_ASYNC_OUT(sourceName, message, targetName) + +/** + * calls \ref etMSCLogger_asyncIn(const char*, const char*, const char*) + * \par + * If \ref ET_MSC_LOGGER_ACTIVATE or \ref ET_ASYNC_MSC_LOGGER_ACTIVATE + * aren't defined this macro is void + */ +#define ET_MSC_LOGGER_ASYNC_IN(sourceName, message, targetName) + +/** + * calls \ref etMSCLogger_setState(const char*, const char*) + * \par + * If \ref ET_MSC_LOGGER_ACTIVATE isn't defined this macro is void + */ +#define ET_MSC_LOGGER_CHANGE_STATE(objectName, stateName) #endif diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/etUnit/etUnit.h b/runtime/org.eclipse.etrice.runtime.c/src/common/etUnit/etUnit.h index 5bfb41b84..98acdf003 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/etUnit/etUnit.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/etUnit/etUnit.h @@ -10,77 +10,320 @@ * *******************************************************************************/ +/** + * \file etUnit.h + * + * a collection of methods for unit testing. The component uses a very simple file output format + * which is translated into JUnit xml format by a separate tool written in Java and also part of the + * eTrice project + * + * \author Thomas Schuetz + */ + #ifndef _ETUNIT_H_ #define _ETUNIT_H_ #include "etDatatypes.h" -/* open / close */ +/** + * opens a file to protocol the test results + * + * \param testResultPath the file path + * \param testFileName the file name + */ void etUnit_open(const char* testResultPath, const char* testFileName); +/** + * closes the protocol file + */ void etUnit_close(void); +/** + * opens a test suite which is a collection of test cases + * + * \param testSuiteName the name of the suite + */ void etUnit_openTestSuite(const char* testSuiteName); +/** + * closes the currently open test suite + */ void etUnit_closeTestSuite(void); +/** + * opens a test case. Multiple test cases can be open at a time + * + * \param testCaseName the name of the test case + * + * \return an id for the test case which has to be used as an identifier + * for the expect... and other methods + */ etInt16 etUnit_openTestCase(const char* testCaseName); +/** + * closes a test case + * + * \param id the test case id + */ void etUnit_closeTestCase(etInt16 id); +/** + * indicate success of a test case + * + * \param id the test case id + */ etBool etUnit_isSuccess(etInt16 id); +/** + * releases the \ref etRuntime_getTerminateSemaphore() and thus makes the program terminate + * + * \param id (unused) + */ void etUnit_testFinished(etInt16 id); /* functions for more convenience for model and generator tests */ +/** + * opens a file, test suite and test case + * + * \param testResultPath the file path + * \param testFileName the file name + * \param testSuiteName the name of the suite + * \param testCaseName the name of the test case + * + * \return an id for the test case which has to be used as an identifier + * for the expect... and other methods + */ etInt16 etUnit_openAll(const char* testResultPath, const char* testFileName, const char* testSuiteName, const char* testCaseName); +/** + * closes test case, suite and file + * + * \param id the test case id + */ void etUnit_closeAll(etInt16 id); -/* boolean values */ +/* + * boolean values + */ + +/** + * calls \ref expectTrue() + */ #define EXPECT_TRUE(id, msg, condition) expectTrue(id, msg, condition, __FILE__, __LINE__) +/** calls \ref expectFalse() */ #define EXPECT_FALSE(id, msg, condition) expectFalse(id, msg, condition, __FILE__, __LINE__) -/* signed integer values */ +/* + * signed integer values + */ +/** calls \ref expectEqualInt8() */ #define EXPECT_EQUAL_INT8(id, msg, expected, actual) expectEqualInt8(id, msg, expected, actual, __FILE__, __LINE__) +/** calls \ref expectEqualInt16() */ #define EXPECT_EQUAL_INT16(id, msg, expected, actual) expectEqualInt16(id, msg, expected, actual, __FILE__, __LINE__) +/** calls \ref expectEqualInt32() */ #define EXPECT_EQUAL_INT32(id, msg, expected, actual) expectEqualInt32(id, msg, expected, actual, __FILE__, __LINE__) -/* unsigned integer values */ +/* + * unsigned integer values + */ +/** calls \ref expectEqualUInt8() */ #define EXPECT_EQUAL_UINT8(id, msg, expected, actual) expectEqualUInt8(id, msg, expected, actual, __FILE__, __LINE__) +/** calls \ref expectEqualUInt16() */ #define EXPECT_EQUAL_UINT16(id, msg, expected, actual) expectEqualUInt16(id, msg, expected, actual, __FILE__, __LINE__) +/** calls \ref expectEqualUInt32() */ #define EXPECT_EQUAL_UINT32(id, msg, expected, actual) expectEqualUInt32(id, msg, expected, actual, __FILE__, __LINE__) -/* float values */ +/* + * float values + */ +/** calls \ref expectEqualFloat32() */ #define EXPECT_EQUAL_FLOAT32(id, msg, expected, actual, precision) expectEqualFloat32(id, msg, expected, actual, precision, __FILE__, __LINE__) +/** calls \ref expectEqualFloat64() */ #define EXPECT_EQUAL_FLOAT64(id, msg, expected, actual, precision) expectEqualFloat64(id, msg, expected, actual, precision, __FILE__, __LINE__) -/* Pointers */ +/* + * Pointers + */ +/** calls \ref expect_equal_void_ptr() */ #define EXPECT_EQUAL_PTR(id, msg, expected, actual) \ expect_equal_void_ptr(id, msg, (const void*) expected, (const void*) actual, __FILE__, __LINE__) -/* more specialized functions */ +/* + * more specialized functions + */ +/** calls \ref expectOrderStart() */ #define EXPECT_ORDER_START(id, list, size) expectOrderStart(id, list, size, __FILE__, __LINE__) +/** calls \ref expectOrder() */ #define EXPECT_ORDER(id, msg, val) expectOrder(id, msg, val, __FILE__, __LINE__) +/** calls \ref expectOrderEnd() */ #define EXPECT_ORDER_END(id, msg, val) expectOrderEnd(id, msg, val, __FILE__, __LINE__) -/* Helpers for adding testcases */ +/* + * Helpers for adding test cases + */ +/** + * code block with calls \ref etUnit_openTestCase() followed by a call to the passed + * test case followed by a call to \ref etUnit_closeTestCase + * + * \param testcase the name of a test case method + */ #define ADD_TESTCASE(testcase) \ { etInt16 id = etUnit_openTestCase(#testcase); \ testcase(id); \ etUnit_closeTestCase(id);} -/* function prototypes, use above macros to call them */ +/* + * function prototypes, use above macros to call them + */ + +/** + * reports an error if the condition is <code>false</code> + * + * \param id the test case id + * \param msg the result message + * \param condition the condition that is expected to be <code>true</code> + * \param file the file name with the test case + * \param line the line + */ void expectTrue(etInt16 id, const char* msg, etBool condition, const char* file, int line); +/** + * reports an error if the condition is <code>true</code> + * + * \param id the test case id + * \param msg the result message + * \param condition the condition that is expected to be <code>false</code> + * \param file the file name with the test case + * \param line the line + */ void expectFalse(etInt16 id, const char* msg, etBool condition, const char* file, int line); +/** + * reports an error if two integers aren't equal + * + * \param id the test case id + * \param msg the result message + * \param expected the expected value + * \param actual the actual value + * \param file the file name with the test case + * \param line the line + */ void expectEqualInt8(etInt16 id, const char* msg, etInt8 expected, etInt8 actual, const char* file, int line); +/** + * reports an error if two integers aren't equal + * + * \param id the test case id + * \param msg the result message + * \param expected the expected value + * \param actual the actual value + * \param file the file name with the test case + * \param line the line + */ void expectEqualInt16(etInt16 id, const char* msg, etInt16 expected, etInt16 actual, const char* file, int line); +/** + * reports an error if two integers aren't equal + * + * \param id the test case id + * \param msg the result message + * \param expected the expected value + * \param actual the actual value + * \param file the file name with the test case + * \param line the line + */ void expectEqualInt32(etInt16 id, const char* msg, etInt32 expected, etInt32 actual, const char* file, int line); +/** + * reports an error if two integers aren't equal + * + * \param id the test case id + * \param msg the result message + * \param expected the expected value + * \param actual the actual value + * \param file the file name with the test case + * \param line the line + */ void expectEqualUInt8(etInt16 id, const char* msg, etUInt8 expected, etUInt8 actual, const char* file, int line); +/** + * reports an error if two integers aren't equal + * + * \param id the test case id + * \param msg the result message + * \param expected the expected value + * \param actual the actual value + * \param file the file name with the test case + * \param line the line + */ void expectEqualUInt16(etInt16 id, const char* msg, etUInt16 expected, etUInt16 actual, const char* file, int line); +/** + * reports an error if two integers aren't equal + * + * \param id the test case id + * \param msg the result message + * \param expected the expected value + * \param actual the actual value + * \param file the file name with the test case + * \param line the line + */ void expectEqualUInt32(etInt16 id, const char* msg, etUInt32 expected, etUInt32 actual, const char* file, int line); +/** + * reports an error if two floats aren't equal + * + * \param id the test case id + * \param msg the result message + * \param expected the expected value + * \param actual the actual value + * \param file the file name with the test case + * \param line the line + */ void expectEqualFloat32(etInt16 id, const char* msg, etFloat32 expected, etFloat32 actual, etFloat32 precision, const char* file, int line); +/** + * reports an error if two floats aren't equal + * + * \param id the test case id + * \param msg the result message + * \param expected the expected value + * \param actual the actual value + * \param file the file name with the test case + * \param line the line + */ void expectEqualFloat64(etInt16 id, const char* msg, etFloat64 expected, etFloat64 actual, etFloat64 precision, const char* file, int line); +/** + * reports an error if two pointers aren't equal + * + * \param id the test case id + * \param msg the result message + * \param expected the expected value + * \param actual the actual value + * \param file the file name with the test case + * \param line the line + */ void expect_equal_void_ptr(etInt16 id, const char* msg, const void* expected, const void* actual, const char* file, int line); +/** + * start of a comparison of an expected order. Initially with this method + * a list of integers is passed. Later calls of \ref expectOrder(etInt16, const char* msg, etInt16, const char* int) + * are compared against the next value in the list and the list pointer is incremented + * + * \param id the test case id + * \param list the list of expected values + * \param size the size of the list + * \param file the file name with the test case + * \param line the line + */ void expectOrderStart(etInt16 id, etInt16* list, etInt16 size, const char* file, int line); +/** + * reports an error if the identifier doesn't match the next value in the list + * + * \param id the test case id + * \param msg the result message + * \param identifier the expected next value + * \param file the file name with the test case + * \param line the line + */ void expectOrder(etInt16 id, const char* msg, etInt16 identifier, const char* file, int line); +/** + * reports an error if the identifier doesn't match the next value in the list which + * is expected to be the last one + * + * \param id the test case id + * \param msg the result message + * \param identifier the expected next value + * \param file the file name with the test case + * \param line the line + */ void expectOrderEnd(etInt16 id, const char* msg, etInt16 identifier, const char* file, int line); #endif /* _ETUNIT_H_ */ diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/helpers/etTimeHelpers.c b/runtime/org.eclipse.etrice.runtime.c/src/common/helpers/etTimeHelpers.c index 439d7a68e..1ce25573e 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/helpers/etTimeHelpers.c +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/helpers/etTimeHelpers.c @@ -12,15 +12,34 @@ #include "helpers/etTimeHelpers.h" -void etTimeHelpers_subtract(etTime *first, etTime* second){ - /* TODO: implement */ +#define _1E9 1000000000 + +static void normalize(etTime* time) { + etInt32 f = time->nSec / _1E9; + if (f>0) { + time->sec += f; + time->nSec -= f*_1E9; + } + else if (f<0) { + ++f; + time->sec -= f; + time->nSec += f*_1E9; + } +} + +void etTimeHelpers_subtract(etTime *first, const etTime* second){ + first->sec -= second->sec; + first->nSec -= second->nSec; + normalize(first); } -void etTimeHelpers_add(etTime *first, etTime* second){ - /* TODO: implement */ +void etTimeHelpers_add(etTime *first, const etTime* second){ + first->sec += second->sec; + first->nSec += second->nSec; + normalize(first); } -etInt32 etTimeHelpers_convertToMSec(etTime *time){ +etInt32 etTimeHelpers_convertToMSec(const etTime *time){ return time->sec * 1000 + time->nSec / 1000000; } diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/helpers/etTimeHelpers.h b/runtime/org.eclipse.etrice.runtime.c/src/common/helpers/etTimeHelpers.h index 6e4098c6d..cafba3ee2 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/helpers/etTimeHelpers.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/helpers/etTimeHelpers.h @@ -10,14 +10,48 @@ * *******************************************************************************/ +/** + * \file etTimeHelpers.h + * + * a collection of useful methods when working with \ref etTime values + * + * \author Thomas Schuetz, Henrik Rentz-Reichert + */ + #ifndef _ETTIMEHELPERS_H_ #define _ETTIMEHELPERS_H_ #include "osal/etTime.h" -void etTime_subtract(etTime *self, etTime* subtractValue); -void etTime_add(etTime *self, etTime* addValue); -etInt32 etTimeHelpers_convertToMSec(etTime *time); +/** + * computes the difference of two times + * + * \param self the this pointer + * \param subtractValue the time to be subtracted + */ +void etTime_subtract(etTime *self, const etTime* subtractValue); + +/** + * computes the sum of two times + * + * \param self the this pointer + * \param addValue the time to be added + */ +void etTime_add(etTime *self, const etTime* addValue); + +/** + * convert a time to milliseconds + * + * \param time the time to be converted + */ +etInt32 etTimeHelpers_convertToMSec(const etTime *time); + +/** + * convert a time from milliseconds + * + * \param result the structure obtaining the result + * \param milliSeconds the time to be converted + */ void etTimeHelpers_convertToEtTime(etTime *result, etInt32 milliSeconds); diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessage.h b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessage.h index 7bba6a1f3..a6c84f26c 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessage.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessage.h @@ -10,17 +10,33 @@ * *******************************************************************************/ +/** + * \file etMessage.h + * + * the message "base class" that is used for asynchronous messages + * + * \author Thomas Schuetz + */ + #ifndef _ETMESSAGE_H_ #define _ETMESSAGE_H_ #include "etDatatypes.h" -typedef struct etMessage{ - struct etMessage* next; - etInt16 address; - etInt16 evtID; +/** + * the message structure + */ +typedef struct etMessage { + struct etMessage* next; /**< pointer to the next message or <code>NULL</code> (single linked list) */ + etInt16 address; /**< the destination address */ + etInt16 evtID; /**< the event id */ } etMessage; +/** + * initializes the message fields ("constructor") + * + * \param self the this pointer + */ void etMessage_init(etMessage* self); #endif /* _ETMESSAGE_H_ */ diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.c b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.c index 96a86b046..59dcb5ed4 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.c +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.c @@ -58,7 +58,7 @@ etMessage* etMessageQueue_pop(etMessageQueue* self){ self->first = self->last = NULL; } else { - /*more than one message in queue -> set first to nex message*/ + /*more than one message in queue -> set first to next message*/ self->first = self->first->next; } diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.h b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.h index e79b57347..3765f39d3 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.h @@ -10,34 +10,103 @@ * *******************************************************************************/ +/** + * \file etMessageQueue.h + * + * this component implements a message queue (fifo) + * + * \author Thomas Schuetz + */ + #ifndef _ETMESSAGEQUEUE_H_ #define _ETMESSAGEQUEUE_H_ #include "messaging/etMessage.h" #include <stddef.h> +/** + * the message queue data structure + */ typedef struct etMessageQueue { - etMessage* first; - etMessage* last; - etInt16 highWaterMark; - etInt16 lowWaterMark; - etInt16 size; + etMessage* first; /**< the head of the list */ + etMessage* last; /**< the tail of the list */ + etInt16 highWaterMark; /**< high water mark for statistical purposes */ + etInt16 lowWaterMark; /**< low water mark for statistical purposes */ + etInt16 size; /**< the size of the list */ } etMessageQueue; +/** + * initializes the queue data fields ("constructor") + * + * \param self the this pointer + */ void etMessageQueue_init(etMessageQueue* self); +/** + * appends a new message to the queue + * + * \param self the this pointer + */ void etMessageQueue_push(etMessageQueue* self, etMessage* msg); +/** + * removes the first message from the queue + * + * \param self the this pointer + * \return the removed message + */ etMessage* etMessageQueue_pop(etMessageQueue* self); +/** + * returns the first message without removing it + * + * \param self the this pointer + * \return the first message without removing it + */ etMessage* etMessageQueue_getFirst(etMessageQueue* self); +/** + * returns the last message without removing it + * + * \param self the this pointer + * \return the last message without removing it + */ etMessage* etMessageQueue_getLast(etMessageQueue* self); +/** + * returns <code>true</code> if the message queue is not empty + * + * \param self the this pointer + * \return <code>true</code> if the message queue is not empty + */ etBool etMessageQueue_isNotEmpty(etMessageQueue* self); +/** + * returns the size of the message queue + * + * \param self the this pointer + * \return the size of the message queue + */ etInt16 etMessageQueue_getSize(etMessageQueue* self); +/** + * returns the high water mark of the message queue + * + * \param self the this pointer + * \return the high water mark of the message queue + */ etInt16 etMessageQueue_getHighWaterMark(etMessageQueue* self); +/** + * returns the low water mark of the message queue + * + * \param self the this pointer + * \return the low water mark of the message queue + */ etInt16 etMessageQueue_getLowWaterMark(etMessageQueue* self); +/** + * resets the low water mark of the message queue to the current + * position (size) of the queue + * + * \param self the this pointer + */ void etMessageQueue_resetLowWaterMark(etMessageQueue* self); diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageReceiver.h b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageReceiver.h index 06cd7df78..566c94707 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageReceiver.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageReceiver.h @@ -10,15 +10,40 @@ * *******************************************************************************/ - +/** + * \file etMessageReceiver.h + * + * method prototypes used by the messaging + * + * \author Thomas Schuetz + */ #ifndef _ETMESSAGERECEIVER_H_ #define _ETMESSAGERECEIVER_H_ #include "messaging/etMessage.h" +/** + * method prototype that receives a message + * + * \param self the this pointer + * \param ifitem a pointer to the interface item that received the message + * \param msg the message + */ typedef void (*etActorReceiveMessage)(void* self, const void* ifitem, const etMessage* msg); + +/** + * method prototype for a dispatcher method + * + * \param msg the message + * + * \return <code>true</code> if the message could be delivered + */ typedef etBool (*etDispatcherReceiveMessage)(const etMessage* msg); + +/** + * prototype for the periodic call to the <code>execute()</code> method of the dispatcher + */ typedef void (*etDispatcherExecute)(void); #endif /* _ETMESSAGERECEIVER_H_ */ diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageService.h b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageService.h index a59ed2178..cd729b9a5 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageService.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageService.h @@ -10,6 +10,14 @@ * *******************************************************************************/ +/** + * \file etMessageService.h + * + * this component implements a message service that delivers messages asynchronously + * + * \author Thomas Schuetz + */ + #ifndef _ETMESSAGESERVICE_H_ #define _ETMESSAGESERVICE_H_ @@ -23,33 +31,54 @@ #include "osal/etSema.h" #include "osal/etTimer.h" +/** the address of the message service */ #define MESSAGESERVICE_ADDRESS 1 +/** the base address for other receivers */ #define BASE_ADDRESS 32 +/** enumeration for execution modes */ typedef enum etMessageService_execmode { - EXECMODE_POLLED, EXECMODE_BLOCKED, EXECMODE_MIXED + EXECMODE_POLLED, /**< polled execution for data driven systems */ + EXECMODE_BLOCKED, /**< blocked execution for asynchronous systems */ + EXECMODE_MIXED /**< mixed execution for mixed systems */ } etMessageService_execmode; +/** + * the data structure for the message buffer (chunks of equal size) + */ typedef struct etBuffer{ - etUInt8 *buffer; /** buffer points to the actual memory position for the message pool */ - etUInt16 maxBlocks; /** number of blocks for the message pool */ - etUInt16 blockSize; /** size of blocks for the message pool */ + etUInt8 *buffer; /**< buffer points to the actual memory position for the message pool */ + etUInt16 maxBlocks; /**< number of blocks for the message pool */ + etUInt16 blockSize; /**< size of blocks for the message pool */ } etBuffer; typedef struct etMessageService { - etMessageQueue messageQueue; /** message queue that holds all used messages */ - etMessageQueue messagePool; /** message pool that holds all free messages */ - etBuffer messageBuffer; /** information about the message buffer that holds information about the actual memory position and size for the message pool */ - etDispatcherReceiveMessage msgDispatcher; /** function pointer to the generated message dispatcher function */ - etThread thread; /** thread for the execution of the message service */ - etMutex poolMutex; /** mutex for synchronizing the access to the message pool */ - etMutex queueMutex; /** mutex for synchronizing the access to the message queue */ - etSema executionSemaphore; /** semaphore for waiting and waking up the execution */ - etTimer timer; /** timer for cyclic calls */ - etMessageService_execmode execmode; /** execution mode*/ + etMessageQueue messageQueue; /**< message queue that holds all used messages */ + etMessageQueue messagePool; /**< message pool that holds all free messages */ + etBuffer messageBuffer; /**< information about the message buffer that holds information about + the actual memory position and size for the message pool */ + etDispatcherReceiveMessage msgDispatcher; /**< function pointer to the generated message dispatcher function */ + etThread thread; /**< thread for the execution of the message service */ + etMutex poolMutex; /**< mutex for synchronizing the access to the message pool */ + etMutex queueMutex; /**< mutex for synchronizing the access to the message queue */ + etSema executionSemaphore; /**< semaphore for waiting and waking up the execution */ + etTimer timer; /**< timer for cyclic calls */ + etMessageService_execmode execmode; /**< execution mode*/ } etMessageService; -/* lifecycle functions to startup, execute and shutdown the message service */ +/** + * initialization (construction) + * + * \param self the this pointer + * \param buffer the buffer for the message pool + * \param maxBlocks the number of (equal sized) message blocks in the buffer + * \param blockSize the size of each message block + * \param stackSize the stack size for the thread in which this service will run + * \param priority the thread priority + * \param interval the polling interval + * \param msgDispatcher the dispatcher method + * \param execmdoe the execution mode for this message service + */ void etMessageService_init( etMessageService* self, etUInt8* buffer, @@ -60,23 +89,81 @@ void etMessageService_init( etTime interval, etDispatcherReceiveMessage msgDispatcher, etMessageService_execmode execmode); + +/** + * start of the message service (starts the associated thread) + * + * \param self the this pointer + */ void etMessageService_start(etMessageService* self); + +/** + * the polling method to be called cyclically + * + * \param self the this pointer + */ void etMessageService_execute(etMessageService* self); + +/** + * stops the message service thread + * + * \param self the this pointer + */ void etMessageService_stop(etMessageService* self); + +/** + * destroys the message service + * + * \param self the this pointer + */ void etMessageService_destroy(etMessageService* self); -/* initialization of message pool */ +/** + * initialization of message pool + * + * \param self the this pointer + */ void etMessageService_initMessagePool(etMessageService* self); -/* message queue interface for push and pop messages */ +/** + * push a message to the queue. The queue access is synchronized. The method notifies the dispatch thread. + * + * \param self the this pointer + * \msg the message to push + */ void etMessageService_pushMessage(etMessageService* self, etMessage* msg); + +/** + * pop a message from the queue. The queue access is synchronized. + * + * \param self the this pointer + * \return the extracted message + */ etMessage* etMessageService_popMessage(etMessageService* self); -/* message pool interface to get and return (push and pop) messages */ +/** + * get a chunk of uninitialized memory interpreted as \ref etMessage from the services memory management + * + * \param self the this pointer + * \param size the size of the message in bytes + * \return a message pointer to a chunk of memory with at least the required size + */ etMessage* etMessageService_getMessageBuffer(etMessageService* self, etUInt16 size); + +/** + * return a chunk of previously obtained memory to the message service memory management + * + * \param self the this pointer + * \param buffer the memory to be freed + */ void etMessageService_returnMessageBuffer(etMessageService* self, etMessage* buffer); -/* functions for debug and service information */ +/** + * returns the low water mark of the message pool + * + * \param self the this pointer + * \return the low water mark of the message pool + */ etInt16 etMessageService_getMessagePoolLowWaterMark(etMessageService* self); diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/modelbase/etActor.h b/runtime/org.eclipse.etrice.runtime.c/src/common/modelbase/etActor.h index a32efdbec..53ab8ce25 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/modelbase/etActor.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/modelbase/etActor.h @@ -10,15 +10,37 @@ * *******************************************************************************/ +/** + * \file etActor.h + * + * the base "class" of a actor + */ + #ifndef _ETACTOR_H_ #define _ETACTOR_H_ #include "etDatatypes.h" #include "modelbase/etPort.h" +/** transition chain ID indicating that no chain fired */ #define NOT_CAUGHT 0 + +/** + * event ID and interface item are code in one integer called trigger. + * The event has a decimal shift of 2 + */ #define EVT_SHIFT 100 +/** + * this function handles system events + * + * \param ifitem the interface item that received the event + * \param evt the event ID + * \param generic_data a data pointer whose type can be inferred from the event type, + * may be <code>NULL</code> + * + * \return <code>true</code> if the event was a system event and thus was already handled + */ etBool handleSystemEvent(InterfaceItemBase* ifitem, int evt, void* generic_data); #endif /* _ETACTOR_H_ */ diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/modelbase/etPort.h b/runtime/org.eclipse.etrice.runtime.c/src/common/modelbase/etPort.h index 4bf86ad18..befef7dcf 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/modelbase/etPort.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/modelbase/etPort.h @@ -10,46 +10,69 @@ * *******************************************************************************/ - +/** + * \file etPort.h + * + * the base "class" of a port + * + * \author Thomas Schuetz, Henrik Rentz-Reichert + */ #ifndef _ETPORT_H_ #define _ETPORT_H_ - #include "messaging/etMessage.h" #include "messaging/etMessageReceiver.h" #include "messaging/etMessageService.h" #include "etRuntimeConfig.h" +/** + * the data structure of a port that holds the constant data + */ typedef struct { - void* varData; - etMessageService* msgService; - etAddressId peerAddress; - etAddressId localId; + void* varData; /**< a pointer to the variable part of the data */ + etMessageService* msgService; /**< the associated message service */ + etAddressId peerAddress; /**< the peer port's address */ + etAddressId localId; /**< the local ID of the port instance in its parent actor */ #ifdef ET_ASYNC_MSC_LOGGER_ACTIVATE - const char* myInstName; - const char* peerInstName; + const char* myInstName; /**< the instance name (i.e. path) of our actor */ + const char* peerInstName; /**< the instance name (i.e. path) of our peer actor */ #endif #ifdef etDEBUG - etAddressId address; - /* thread ID from msg service: msgService->threadId */ + etAddressId address; /**< the port's adress */ + /* thread ID from msg service: msgService->threadId */ #endif } etPort; +/** + * data needed for a sub port of a replicated port + */ typedef struct { - etPort port; - etAddressId index; + etPort port; /**< the sub port data */ + etAddressId index; /**< the offset in the array of sub ports */ } etReplSubPort; +/** + * data of a replicated port + */ typedef struct { - etInt16 size; - const etReplSubPort* ports; + etInt16 size; /**< the number of sub ports */ + const etReplSubPort* ports; /**< pointers to the sub ports */ } etReplPort; typedef etPort InterfaceItemBase; /*void etPort_receive(const etPort* self, const etMessage* msg);*/ + +/** + * sends a message + * + * \param self the this pointer + * \param evtId the event id + * \param size the size of the data + * \param a pointer to the data (may be <code>NULL</code>) + */ void etPort_sendMessage(const etPort* self, etInt16 evtId, int size, void* data); diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etMutex.h b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etMutex.h index 2c67cad14..27d0c1118 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etMutex.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etMutex.h @@ -11,13 +11,16 @@ * *******************************************************************************/ -#ifndef _ETMUTEX_H_ -#define _ETMUTEX_H_ - /** + * \file etMutex.h + * * etMutex.h defines a generic interface for platform specific implementations of a mutex * - * */ + * \author Thomas Schuetz, Thomas Jung + */ + +#ifndef _ETMUTEX_H_ +#define _ETMUTEX_H_ #include "etDatatypes.h" diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etPlatformLifecycle.h b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etPlatformLifecycle.h index 8bf41170f..c6dc1e580 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etPlatformLifecycle.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etPlatformLifecycle.h @@ -10,37 +10,40 @@ * *******************************************************************************/ -#ifndef _ETPLATFORMLIFECYCLE_H_ -#define _ETPLATFORMLIFECYCLE_H_ - /** + * \file etPlatformLifecycle.h + * * etPlatformLifecycle.h defines a generic interface for platform specific startup and shutdown functions * those functions are called at specific points during the lifecycle of an eTrice application * they can be used to integrate and execute platform or OS specific code * - * */ + * \author Thomas Schuetz + */ + +#ifndef _ETPLATFORMLIFECYCLE_H_ +#define _ETPLATFORMLIFECYCLE_H_ #include "etDatatypes.h" /** * Platform specific code, called at the start of the system startup of the main function - * */ + */ void etUserEntry(void); /** * Platform specific code, called at the end of the startup right before the start of the actual application - * */ + */ void etUserPreRun(void); /** * Platform specific code, called at the beginning of the shutdown right after before the stop of the actual application - * */ + */ void etUserPostRun(void); /** * Platform specific code, called at the end of the system shutdown of the main function - * */ + */ void etUserExit(void); #endif /* _ETPLATFORMLIFECYCLE_H_ */ diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etSema.h b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etSema.h index 31afdc271..e1b115308 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etSema.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etSema.h @@ -10,12 +10,15 @@ * *******************************************************************************/ -#ifndef _ETSEMA_H_ -#define _ETSEMA_H_ - /** + * \file etSema.h + * * etSema.h defines a generic interface for platform specific implementations of a semaphore + * + * \author Thomas Schuetz */ +#ifndef _ETSEMA_H_ +#define _ETSEMA_H_ #include "etDatatypes.h" diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTcpSockets.h b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTcpSockets.h index 293feaaf0..ce332f31b 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTcpSockets.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTcpSockets.h @@ -10,6 +10,14 @@ * *******************************************************************************/ +/** + * \file etTcpSockets.h + * + * abstraction of a TCP/IP socket client and server + * + * \author Henrik Rentz-Reichert + */ + #ifndef _ETTCPSOCKETS_H_ #define _ETTCPSOCKETS_H_ @@ -140,7 +148,7 @@ void etFreeSocketConnectionData(etSocketConnectionData* data); /** * connect a socket server - * @param addr the internet address given as quadrupel, if {@code NULL} then local host is assumed + * @param addr the internet address given as quadrupel, if <code>NULL</code> then local host is assumed * @param port the port to which the connection should be established * @param self the client data * @return an error code of type {@link etSocketError} diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etThread.h b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etThread.h index 172723db6..a176f9d6a 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etThread.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etThread.h @@ -10,14 +10,16 @@ * *******************************************************************************/ -#ifndef _ETTHREAD_H_ -#define _ETTHREAD_H_ - /** - * etThread.h defines a generic interface for platform specific implementations of a thread + * \file etThread.h * - * */ - + * defines a generic interface for platform specific implementations of a thread + * + * \author Thomas Schuetz, Thomas Jung + * + */ +#ifndef _ETTHREAD_H_ +#define _ETTHREAD_H_ #include "etDatatypes.h" diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTime.h b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTime.h index a9c9450ce..8a68f4102 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTime.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTime.h @@ -10,21 +10,25 @@ * *******************************************************************************/ -#ifndef _ETTIME_H_ -#define _ETTIME_H_ - /** - * etTime.h defines a generic interface for platform specific implementations of services around time + * \file etTime.h + * + * defines a generic interface for platform specific implementations of services around time + * + * \author Thomas Schuetz */ +#ifndef _ETTIME_H_ +#define _ETTIME_H_ + #include "etDatatypes.h" /** * time definition composed by the number of seconds and the number of nano seconds */ typedef struct etTime { - etInt32 sec; - etInt32 nSec; + etInt32 sec; /**< seconds */ + etInt32 nSec; /**< nanoseconds */ } etTime; /** diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTimer.h b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTimer.h index 6ac5f0a48..827c2a025 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTimer.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTimer.h @@ -10,6 +10,13 @@ * *******************************************************************************/ +/** + * \file etTimer.h + * + * a timer abstraction + * + * \author Thomas Jung + */ #ifndef _ETTIMER_H_ #define _ETTIMER_H_ @@ -25,12 +32,12 @@ typedef void (*etTimerFunction)(void* data); /** * etThread holds all data needed to handle a thread instance * the struct has to be filled before calling etThread_construct except for osData and osId - **/ + */ typedef struct etTimer{ - etTime timerInterval; /**< timer interval **/ - etTimerFunction timerFunction; /**< call back function to be called by timer -> has to be filled in by caller of etTimer_construct **/ - void* timerFunctionData; /**< the data that are passed to the timer function **/ - etOSTimerData osTimerData; /**< OS specific timer id (e.g. handle or id) -> is filled in by etTimer_construct **/ + etTime timerInterval; /**< timer interval */ + etTimerFunction timerFunction; /**< call back function to be called by timer -> has to be filled in by caller of etTimer_construct */ + void* timerFunctionData; /**< the data that are passed to the timer function */ + etOSTimerData osTimerData; /**< OS specific timer id (e.g. handle or id) -> is filled in by etTimer_construct */ } etTimer; /** diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/runtime/etRuntime.h b/runtime/org.eclipse.etrice.runtime.c/src/common/runtime/etRuntime.h index 5b9aa281a..a2bc7901e 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/runtime/etRuntime.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/runtime/etRuntime.h @@ -13,8 +13,21 @@ #ifndef _ETRUNTIME_H_ #define _ETRUNTIME_H_ +/** + * \file etRuntime.h + * + * runtime methods + * + * \author Thomas Schuetz + */ + #include "osal/etSema.h" +/** + * a global semaphore used to terminate the application in headless mode + * + * \return the semaphore + */ etSema* etRuntime_getTerminateSemaphore(); #endif /* _ETRUNTIME_H_ */ diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/runtime/etThreadList.h b/runtime/org.eclipse.etrice.runtime.c/src/common/runtime/etThreadList.h index 830ae61fd..27c889a3c 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/common/runtime/etThreadList.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/common/runtime/etThreadList.h @@ -10,15 +10,20 @@ * *******************************************************************************/ +/** + * \file etThreadList.h + * + * NOT IMPLEMENTED YET + * + * holds a complete list of all threads + * + */ + #ifndef _etThreadController_H_ #define _etThreadController_H_ #include "osal/etThread.h" -/** - * etThreadController holds a complete list of all threads - * - **/ typedef struct etThreadController{ etThread* threadList; /**< list of all thread data (as array) **/ int32 size; /**< size of the list **/ diff --git a/runtime/org.eclipse.etrice.runtime.c/src/config/etRuntimeConfig.h b/runtime/org.eclipse.etrice.runtime.c/src/config/etRuntimeConfig.h index 3e2992349..52187eddf 100644 --- a/runtime/org.eclipse.etrice.runtime.c/src/config/etRuntimeConfig.h +++ b/runtime/org.eclipse.etrice.runtime.c/src/config/etRuntimeConfig.h @@ -10,18 +10,36 @@ * *******************************************************************************/ +/** + * file etRuntimeConfig.h + * + * preprocessor switches that configure the runtime + * + * \author Thomas Schuetz + */ + #ifndef ETGLOBALFLAGS_H_ #define ETGLOBALFLAGS_H_ /* flags for debugging */ + /* MSC logger */ -#define ET_MSC_LOGGER_ACTIVATE /* needs ET_LOGGER_ACTIVATE */ -//#define ET_SYNC_MSC_LOGGER_ACTIVATE /* needs ET_MSC_LOGGER_ACTIVATE */ -#define ET_ASYNC_MSC_LOGGER_ACTIVATE /* needs ET_MSC_LOGGER_ACTIVATE */ + +/** switches the logger on */ #define ET_LOGGER_ACTIVATE +/** switches the MSC logger on, needs \ref ET_LOGGER_ACTIVATE */ +#define ET_MSC_LOGGER_ACTIVATE + +/** switches the logging of asynchronous messages on, needs \ref ET_MSC_LOGGER_ACTIVATE */ +#undef ET_SYNC_MSC_LOGGER_ACTIVATE +/** switches the logging of synchronous messages on, needs \ref ET_MSC_LOGGER_ACTIVATE */ +#define ET_ASYNC_MSC_LOGGER_ACTIVATE + /* data logger */ + +/** switches the data logger on */ #define ET_DATA_LOGGER_ACTIVATE /* timing and scheduling */ @@ -29,7 +47,7 @@ //#define ET_RUNTIME_MAXLOOP 100 /*#define ET_RUNTIME_ENDLESS*/ -/* enable multi threading (e.g. for protection of message queues) */ +/** enable multi threading (e.g. for protection of message queues) */ #define ET_MULTI_THREADING #endif /* ETGLOBALFLAGS_H_ */ |