Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorHenrik Rentz-Reichert2013-12-03 10:58:46 -0500
committerHenrik Rentz-Reichert2013-12-04 09:43:46 -0500
commit14009fe85a0e9a4e4b26cd4da4410097b93b3aa7 (patch)
tree71dc85f2587b3695a5953e6277e9fb665303a4ff /runtime/org.eclipse.etrice.runtime.c
parent8c8074b44e71bd77bbf521e444e42595c65e7120 (diff)
downloadorg.eclipse.etrice-14009fe85a0e9a4e4b26cd4da4410097b93b3aa7.tar.gz
org.eclipse.etrice-14009fe85a0e9a4e4b26cd4da4410097b93b3aa7.tar.xz
org.eclipse.etrice-14009fe85a0e9a4e4b26cd4da4410097b93b3aa7.zip
406871: [runtime.c] finish doxygen documentation for runtime.c
https://bugs.eclipse.org/bugs/show_bug.cgi?id=406871 Change-Id: I2973b87bebc726a7aafa89d7b181bf7f16059834
Diffstat (limited to 'runtime/org.eclipse.etrice.runtime.c')
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/run_doxygen_runtime.c.launch6
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory.h6
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FixedSize.h8
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FreeList.c23
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/base/etMemory_FreeList.h42
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etDataLogger.h76
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etLogger.h71
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/debugging/etMSCLogger.h128
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/etUnit/etUnit.h261
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/helpers/etTimeHelpers.c29
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/helpers/etTimeHelpers.h40
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessage.h24
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.c2
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.h79
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageReceiver.h27
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageService.h125
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/modelbase/etActor.h22
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/modelbase/etPort.h51
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/osal/etMutex.h11
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/osal/etPlatformLifecycle.h19
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/osal/etSema.h9
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTcpSockets.h10
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/osal/etThread.h14
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTime.h16
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/osal/etTimer.h17
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/runtime/etRuntime.h13
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/runtime/etThreadList.h13
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/config/etRuntimeConfig.h26
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_ */

Back to the top