1 /** ---------------------------------------------------------------------------
2 * \file EcEap.h
3 * \copyright acontis technologies GmbH, Weingarten, Germany
4 * \author mdu
5 * \brief Acontis EAP stack API header file
6 *---------------------------------------------------------------------------*/
8 #ifndef INC_ECEAP
9 #define INC_ECEAP 1
11 /*-INCLUDES------------------------------------------------------------------*/
12 #ifndef INC_ECTYPE
13 #include <EcType.h>
14 #endif
15 #ifndef INC_ECOS
16 #include <EcOs.h>
17 #endif
18 #ifndef INC_ECLINK
19 #include <EcLink.h>
20 #endif
21 #ifndef INC_ECERROR
22 #include <EcError.h>
23 #endif
25 /*-COMPILER SETTINGS---------------------------------------------------------*/
26 #ifdef __cplusplus
27 extern "C"
28 {
29 #endif
31 /*-DEFINES-------------------------------------------------------------------*/
32 #define EAP_E_CFGFILENOTFOUND ((EC_T_DWORD)0x98140000)
33 #define EAP_SZTXT_E_CFGFILENOTFOUND "EDC file not found"
35 #define EAP_E_WRONGSTATE ((EC_T_DWORD)0x98140001)
36 #define EAP_SZTXT_E_WRONGSTATE "Wrong EAP state"
38 #define EAP_E_INITTRANSMITDATA ((EC_T_DWORD)0x98140002)
39 #define EAP_SZTXT_E_INITTRANSMITDATA "Can not intialize transmit data"
41 #define EAP_STATE_CHANGE_TIMEOUT (10000)
43 /*-TYPEDEFS------------------------------------------------------------------*/
44 #include EC_PACKED_INCLUDESTART(1)
45 typedef struct _EC_T_GUID
46 {
47 EC_T_DWORD dwData1;
48 EC_T_WORD dwData2;
49 EC_T_WORD dwData3;
50 EC_T_WORD dwData4;
51 EC_T_BYTE byData5[6];
52 } EC_PACKED(1) EC_T_GUID;
53 #include EC_PACKED_INCLUDESTOP
55 /** EAP state */
56 typedef enum _EAP_T_STATE
57 {
58 eEapState_UNKNOWN = 0, /*< unknown */
59 eEapState_INIT = 1, /*< init */
60 eEapState_PREOP = 2, /*< pre-operational */
61 eEapState_SAFEOP = 4, /*< safe operational */
62 eEapState_OP = 8, /*< operational */
63 eEapState_BOOTSTRAP = 3, /*< BootStrap */
65 /* Borland C++ datatype alignment correction */
66 eEapState_BCppDummy = 0xFFFFFFFF
67 } EAP_T_STATE;
69 /** Configuration parameter type */
70 typedef enum _EAP_T_CNF_TYPE
71 {
72 eEapCnfType_Unknown = 0,
73 eEapCnfType_Filename = 1,
75 /* Borland C++ datatype alignment correction */
76 eEapCnfType_BCppDummy = 0xFFFFFFFF
77 } EAP_T_CNF_TYPE;
79 /** Configuration parameter description */
80 typedef struct _EAP_T_CONFIGPARM_DESC
81 {
82 EAP_T_CNF_TYPE eCnfType; /*< Type of configuration data (file/stream) */
83 EC_T_BYTE* pbyData; /*< Configuration data */
84 EC_T_DWORD dwLen; /*< length of configuration data */
85 } EAP_T_CONFIGPARM_DESC, *EAP_PT_CONFIGPARM_DESC;
87 /** Protocol type */
88 typedef enum _EAP_T_PROTOCOL_TYPE
89 {
90 eEapProtocol_Ethernet = 0, /*< EtherType 0x88A4, optimized link layer */
91 eEapProtocol_UDP = 1, /*< UPD Socket 0x88A4 */
92 eEapProtocol_TCP = 2 /*< TCP Socket 0x88A4, NOT SUPPORTED FOR NOW */
93 } EAP_T_PROTOCOL_TYPE;
95 /** EAP stack initialization parameters */
96 typedef struct _EAP_T_INITPARMS
97 {
98 EAP_T_PROTOCOL_TYPE eProtocolType; /**< Protocol type */
99 EC_T_WORD wSocket; /**< Socket port (UDP, TCP) */
100 EC_T_LINK_PARMS* poLinkParms; /**< Parameters for the link layer */
101 EC_T_BYTE abyIpAddr[4]; /**< IP address */
102 } EAP_T_INITPARMS, *EAP_PT_INITPARMS;
104 /** EAP variable information */
105 /** \sa eapGetVarInfo() */
106 typedef struct _EAP_T_VAR_INFO
107 {
108 EC_T_WORD wSize; /**< variable size in bytes */
109 EC_T_WORD wIndex; /**< index of corresponding object */
110 EC_T_CHAR szName[256]; /**< name */
111 EC_T_CHAR szSymbolName[256]; /**< symbolic name */
112 EC_T_GUID GUID; /**< type as GUID */
113 } EAP_T_VAR_INFO, *EAP_PT_VAR_INFO;
115 typedef EC_T_HANDLE EAP_VAR_HANDLE;
116 typedef EC_T_VOID (*EAP_T_PFVAR_CB)(EC_T_VOID* Context, EC_T_HANDLE hPort, EAP_VAR_HANDLE hVar);
118 /*-FUNCTION DECLARATION------------------------------------------------------*/
120 /********************************************************************************/
121 /** \brief Gets the version of EAP stack.
122 *
123 * \param [out] dwVersion Softwareversion
124 *
125 * \return always EC_E_NOERROR
126 */
127 ATECAT_API EC_T_DWORD eapGetVersion(EC_T_DWORD *dwVersion);
129 /********************************************************************************/
130 /** \brief Configures the EAP stack.
131 * \details Reads a configuration file (EDC).
132 *
133 * \param [in] hPort EAP stack handle
134 * \param [in] oConfig Parameter description structure
135 * \sa EAP_T_CONFIGPARM_DESC
136 *
137 * \return Error code or EC_E_NOERROR if succeeded
138 */
139 ATECAT_API EC_T_DWORD eapConfigure(EC_T_HANDLE hPort, EAP_T_CONFIGPARM_DESC oConfig);
141 /********************************************************************************/
142 /** \brief Initializes and starts the EAP stack.
143 * \details Gives back a stack handle, this handle will used
144 * in further functions calls
145 *
146 * \param [in] oParms Initialization parameters structure
147 * \param [out] phPort EAP stack handle
148 * \sa EAP_T_INITPARMS
149 *
150 * \return Error code or EC_E_NOERROR if succeeded
151 */
152 ATECAT_API EC_T_DWORD eapInit(EAP_T_INITPARMS oParms, EC_T_HANDLE* hPort);
153 /********************************************************************************/
154 /** \brief Deinitializes the EAP stack
155 * \details After this function call the handle hPort is invalid and can not
156 * be used for further calls.
157 *
158 * \param [in] hPort EAP stack handle
159 *
160 * \return Error code or EC_E_NOERROR if succeeded
161 */
162 ATECAT_API EC_T_DWORD eapDeinit(EC_T_HANDLE hPort);
164 /********************************************************************************/
165 /** \brief Switches the state of the stack SM (state machine)
166 *
167 * \param [in] hPort EAP stack handle
168 * \param [in] eNewState New SM state
169 * \param [in] dwTimeout Time out for operation completion
170 * \sa EAP_T_STATE
171 *
172 * \return Error code or EC_E_NOERROR if succeeded
173 */
174 ATECAT_API EC_T_DWORD eapSetState(EC_T_HANDLE hPort, EAP_T_STATE eNewState, EC_T_DWORD dwTimeout);
175 /********************************************************************************/
176 /** \brief Gives back the current state of the stack SM (state machine)
177 *
178 * \param [in] hPort EAP stack handle
179 * \param [out] eState Current SM state (\sa ::EAP_T_STATE)
180 * \sa EAP_T_STATE
181 *
182 * \return Error code or EC_E_NOERROR if succeeded
183 */
184 ATECAT_API EC_T_DWORD eapGetState(EC_T_HANDLE hPort, EAP_T_STATE* eState);
186 /********************************************************************************/
187 /** \brief Returns a number of transmit variables (0x6xxx objects)
188 * \details The returned value can be used to allocate memory for
189 * a eapGetTxVarList() call
190 * \warning Memory for wNumOfVars has to be allocated prior this function call!
191 *
192 * \param [in] hPort EAP stack handle
193 * \param [out] wNumOfVars Number of transmit variables (0x6xxx objects)
194 *
195 * \return Error code or EC_E_NOERROR if succeeded
196 *
197 * \sa eapGetTxVarList()
198 */
199 ATECAT_API EC_T_DWORD eapGetNumOfTxVars(EC_T_HANDLE hPort, EC_T_WORD* wNumOfVars);
200 /********************************************************************************/
201 /** \brief Returns an array with transmit varaibles indexes (0x6000 to 0x6FFF)
202 * of configured variables.
203 * \details The amount of variables is returned by eapGetNumOfTxVars()
204 * \warning Memory for aIndexes has to be allocated prior this function call!
205 *
206 * \param [in] hPort EAP stack handle
207 * \param [out] aIndexes Transmit variables indexes (0x6000 to 0x6FFF)
208 *
209 * \return Error code or EC_E_NOERROR if succeeded
210 *
211 * \sa eapGetNumOfTxVars()
212 */
213 ATECAT_API EC_T_DWORD eapGetTxVarList(EC_T_HANDLE hPort, EC_T_WORD* aIndexes);
215 /********************************************************************************/
216 /** \brief Returns a number of receive variables (0x7xxx objects)
217 * \details The returned value can be used to allocate memory for
218 * a eapGetRxVarList() call
219 * \warning Memory for wNumOfVars has to allocated prior this function call!
220 *
221 * \param [in] hPort EAP stack handle
222 * \param [out] wNumOfVars Number of receive variables (0x7xxx objects)
223 *
224 * \return Error code or EC_E_NOERROR if succeeded
225 *
226 * \sa eapGetRxVarList()
227 */
228 ATECAT_API EC_T_DWORD eapGetNumOfRxVars(EC_T_HANDLE hPort, EC_T_WORD* wNumOfVars);
229 /********************************************************************************/
230 /** \brief Returns an array with receive varaibles indexes (0x7000 to 0x7FFF)
231 * of configured variables.
232 * \details The amount of variables is returned by eapGetNumOfRxVars()
233 * \warning Memory for aIndexes has to allocated prior this function call!
234 *
235 * \param [in] hPort EAP stack handle
236 * \param [out] aIndexes Receive variables indexes (0x7000 to 0x7FFF)
237 *
238 * \return Error code or EC_E_NOERROR if succeeded
239 *
240 * \sa eapGetNumOfRxVars()
241 */
242 ATECAT_API EC_T_DWORD eapGetRxVarList(EC_T_HANDLE hPort, EC_T_WORD* aIndexes);
244 /********************************************************************************/
245 /** \brief Gets variable handle by object index
246 *
247 * \details The object index has to be between 0x6000..0x6FFF and 0x7000..0x7FFF.
248 * The memory for hHandle has to be allocated prior function call.
249 * The handle will be use for further calls like eapGetVarInfo() or eapVarRead()
250 *
251 * \param [in] hPort EAP stack handle
252 * \param [out] hHandle handle of an EAP variable
253 * \param [in] wIndex object index (within 0x6nnn or 0x7nnn range)
254 *
255 * \return Error code or EC_E_NOERROR if succeeded
256 *
257 * \sa eapGetHandleByName()
258 */
259 ATECAT_API EC_T_DWORD eapGetHandleByIndex(EC_T_HANDLE hPort, EAP_VAR_HANDLE* hVar, EC_T_WORD wIndex);
260 /********************************************************************************/
261 /** \brief Gets variable handle by name
262 *
263 * \details If more than one variable with given name exists, a first one (smallest
264 * object index) will be taken. The handle will be use for further calls
265 * like eapGetVarInfo() or eapVarRead().
266 *
267 * \param [in] hPort EAP stack handle
268 * \param [out] hHandle handle of an EAP variable
269 * \param [in] szName variable name
270 *
271 * \return Error code or EC_E_NOERROR if succeeded
272 *
273 * \sa eapGetHandleByIndex()
274 */
275 ATECAT_API EC_T_DWORD eapGetHandleByName(EC_T_HANDLE hPort, EAP_VAR_HANDLE* hVar, EC_T_CHAR *szName);
276 /********************************************************************************/
277 /** \brief Gets information about a variable
278 *
279 * \details The variable handle has to be obtained prior function call.
280 * The buffer memory for pVarInfo has to be allocated as well.
281 *
282 * \param [in] hPort EAP stack handle
283 * \param [in] hVar handle of an EAP variable
284 * \param [out] pVarInfo information structure
285 * \sa EAP_T_VAR_INFO
286 *
287 * \return Error code or EC_E_NOERROR if succeeded
288 *
289 * \sa eapGetHandlebyIndex(), eapGetHandleByName()
290 */
291 ATECAT_API EC_T_DWORD eapGetVarInfo(EC_T_HANDLE hPort, EAP_VAR_HANDLE hVar, EAP_T_VAR_INFO* pVarInfo);
293 /********************************************************************************/
294 /** \brief Registers a callback function to be called,
295 * when a variable changes its state
296 *
297 * \details The variable handle has to be obtained prior function call.
298 * Use EC_NULL as fnCallback to unregister.
299 *
300 * \param [in] hPort EAP stack handle
301 * \param [in] hVar handle of an EAP variable
302 * \param [in] fnCallback callback function
303 * \param [in] pvContext context, can be NULL
304 * \sa EAP_T_PFVAR_CB
305 *
306 * \return Error code or EC_E_NOERROR if succeeded
307 *
308 * \sa eapGetHandlebyIndex(), eapGetHandleByName()
309 */
310 ATECAT_API EC_T_DWORD eapVarRegisterCallback(EC_T_HANDLE hPort, EAP_VAR_HANDLE hVar, EAP_T_PFVAR_CB fnCallback, EC_T_VOID* pvContext);
312 /********************************************************************************/
313 /** \brief Returns a value of a variable
314 *
315 * \details The variable handle has to be obtained prior function call.
316 * The buffer memory has to be allocated as well. During operation the
317 * curresponding memory will be locked.
318 * The parameter dwDataLen [in]/[out] contains the buffer size before
319 * and after function call
320 *
321 * \param [in] hPort EAP stack handle
322 * \param [in] hVar handle of an EAP variable
323 * \param [out] pData data buffer
324 * \param [in,out] dwDataLen buffer size before/after function call
325 *
326 * \return Error code or EC_E_NOERROR if succeeded
327 *
328 * \sa eapGetHandlebyIndex(), eapGetHandleByName(), eapVarReadNoLock(),
329 * eapVarWriteNoLock(), eapVarWrite()
330 */
331 ATECAT_API EC_T_DWORD eapVarRead(EC_T_HANDLE hPort, EAP_VAR_HANDLE hVar, EC_T_PVOID pData, EC_T_DWORD* dwDataLen);
332 /********************************************************************************/
333 /** \brief Writes a value to a variable
334 *
335 * \details The variable handle has to be obtained prior function call.
336 * During operation the curresponding memory will be locked.
337 * the parameter dwDataLen [in]/[out] contains the buffer size
338 * before and after function call.
339 *
340 * \param [in] hPort EAP stack handle
341 * \param [in] hVar handle of an EAP variable
342 * \param [in] pData data buffer
343 * \param [in,out] dwDataLen buffer size before/after function call
344 *
345 * \return Error code or EC_E_NOERROR if succeeded
346 *
347 * \sa eapGetHandlebyIndex(), eapGetHandleByName(), eapVarReadNoLock(),
348 * eapVarWriteNoLock(), eapVarRead()
349 */
350 ATECAT_API EC_T_DWORD eapVarWrite(EC_T_HANDLE hPort, EAP_VAR_HANDLE hVar, EC_T_PVOID pData, EC_T_DWORD* dwDataLen);
351 /********************************************************************************/
352 /** \brief Sets the memory lock for access to variables.
353 *
354 * \details In a multithreading enveronment protects against unexpected
355 * memory changes.
356 *
357 * \param [in] hPort EAP stack handle
358 *
359 * \return Error code or EC_E_NOERROR if succeeded
360 *
361 * \sa eapVarReadNoLock(), eapVarWriteNoLock(), eapVarUnlock()
362 */
363 ATECAT_API EC_T_DWORD eapVarLock(EC_T_HANDLE hPort);
364 /********************************************************************************/
365 /** \brief Releases locked memory for access after eapVarLock()
366 *
367 * \param [in] hPort EAP stack handle
368 *
369 * \return Error code or EC_E_NOERROR if succeeded
370 *
371 * \sa eapVarReadNoLock(), eapVarWriteNoLock(), eapVarLock()
372 */
373 ATECAT_API EC_T_DWORD eapVarUnlock(EC_T_HANDLE hPort);
375 /********************************************************************************/
376 /** \brief Returns a value of a variable
377 *
378 * \details The variable handle has to be obtained prior function call.
379 * The buffer memory has to be allocated as well.
380 * No memory lock during operation. The parameter dwDataLen [in]/[out]
381 * contains the buffer size before and after function call.
382 *
383 * \param [in] hPort EAP stack handle
384 * \param [in] hVar handle of an EAP variable
385 * \param [out] pData data buffer
386 * \param [in,out] dwDataLen buffer size bifore/after function call
387 *
388 * \return Error code or EC_E_NOERROR if succeeded
389 *
390 * \sa eapGetHandlebyIndex(), eapGetHandleByName(), eapVarLock(), eapVarUnlock(),
391 * eapVarRead()
392 */
393 ATECAT_API EC_T_DWORD eapVarReadNoLock(EC_T_HANDLE hPort, EAP_VAR_HANDLE hVar, EC_T_PVOID pData, EC_T_DWORD* dwDataLen);
394 /********************************************************************************/
395 /** \brief Writes a value to a variable
396 *
397 * \details The variable handle has to be obtained prior function call.
398 * No memory lock during operation. the parameter dwDataLen [in]/[out]
399 * contains the buffer size before and after function call.
400 *
401 * \param [in] hPort EAP stack handle
402 * \param [in] hVar handle of an EAP variable
403 * \param [in] pData data buffer
404 * \param [in,out] dwDataLen buffer size before/after function call
405 *
406 * \return Error code or EC_E_NOERROR if succeeded
407 *
408 * \sa eapGetHandlebyIndex(), eapGetHandleByName(), eapVarLock(), eapVarUnlock(),
409 * eapVarWrite()
410 */
411 ATECAT_API EC_T_DWORD eapVarWriteNoLock(EC_T_HANDLE hPort, EAP_VAR_HANDLE hVar, EC_T_PVOID pData, EC_T_DWORD* dwDataLen);
413 /********************************************************************************/
414 /** \brief Process receive data frames
415 *
416 * \details This function has to be called cyclically in oreder to maintain
417 * proper communication. The data can be only received synchron
418 * to the device cycle.
419 *
420 * \param [in] hPort EAP stack handle
421 *
422 * \return Error code or EC_E_NOERROR if succeeded
423 *
424 * \sa eapJobProcessTxData(), eapGetCycleTime(), eapSetCycleTime(),
425 * eapCalculateCycleTime(), eapJobOnTimer()
426 */
427 ATECAT_API EC_T_DWORD eapJobProcessRxData(EC_T_HANDLE hPort);
428 /********************************************************************************/
429 /** \brief Process transmit data frames
430 *
431 * \details This function has to be called cyclically in oreder to maintain
432 * proper communication. The data can be only sent synchron to
433 * the device cycle.
434 *
435 * \param [in] hPort EAP stack handle
436 *
437 * \return Error code or EC_E_NOERROR if succeeded
438 *
439 * \sa eapJobProcessRxData(), eapGetCycleTime(), eapSetCycleTime(),
440 * eapCalculateCycleTime(), eapJobOnTimer()
441 */
442 ATECAT_API EC_T_DWORD eapJobProcessTxData(EC_T_HANDLE hPort);
443 /********************************************************************************/
444 /** \brief Performs cyclical tasks
445 *
446 * \details Has to be called cyclically in the main application.
447 *
448 * \param [in] hPort EAP stack handle
449 *
450 * \return Error code or EC_E_NOERROR if succeeded
451 *
452 * \sa eapJobProcessRxData(), eapJobProcessTxData(), eapGetCycleTime(),
453 * eapCalculateCycleTime(), eapSetCycleTime()
454 */
455 ATECAT_API EC_T_DWORD eapJobOnTimer(EC_T_HANDLE hPort);
457 /********************************************************************************/
458 /** \brief Gets the actual EAP cycle time
459 *
460 * \param [in] hPort EAP stack handle
461 * \param [out] dwCycleTime cycle time in uS
462 *
463 * \return Error code or EC_E_NOERROR if succeeded
464 *
465 * \sa eapJobProcessRxData(), eapJobProcessTxData(), eapSetCycleTime(),
466 * eapCalculateCycleTime(), eapJobOnTimer()
467 */
468 ATECAT_API EC_T_DWORD eapGetCycleTime(EC_T_HANDLE hPort, EC_T_DWORD* dwCycleTime);
469 /********************************************************************************/
470 /** \brief Calculates the best cycle time for proper communication
471 *
472 * \details The cycle time value will be calculated as "Greatest Common Divider"
473 * of all timings in the EAP stack.
474 *
475 * \param [in] hPort EAP stack handle
476 * \param [out] dwCycleTime cycle time in uS
477 *
478 * \return Error code or EC_E_NOERROR if succeeded
479 *
480 * \sa eapJobProcessRxData(), eapJobProcessTxData(), eapSetCycleTime(),
481 * eapCalculateCycleTime(), eapGetCycleTime(), eapJobOnTimer()
482 */
483 ATECAT_API EC_T_DWORD eapCalculateCycleTime(EC_T_HANDLE hPort, EC_T_DWORD* dwCycleTime);
484 /********************************************************************************/
485 /** \brief Sets a new EAP cycle time
486 *
487 * \param [in] hPort EAP stack handle
488 * \param [out] dwCycleTime cycle time in uS
489 *
490 * \return Error code or EC_E_NOERROR if succeeded
491 *
492 * \sa eapJobProcessRxData(), eapJobProcessTxData(), eapGetCycleTime(),
493 * eapCalculateCycleTime(), eapJobOnTimer()
494 */
495 ATECAT_API EC_T_DWORD eapSetCycleTime(EC_T_HANDLE hPort, EC_T_DWORD dwCycleTime);
497 /********************************************************************************/
498 /** \brief Returns text by id, i.e. textual description of an error code
499 *
500 * \param [in] dwTextId text id
501 *
502 * \return Text as a NULL terminated character string (can be NULL if no text found)
503 */
504 ATECAT_API const EC_T_CHAR* eapGetText(EC_T_DWORD dwTextId);
506 ATECAT_API EC_T_VOID ecatPerfMeasInit( EC_T_TSC_MEAS_DESC* pTscMeasDesc, EC_T_UINT64 dwlFreqSet, EC_T_DWORD dwNumMeas, EC_T_FNMESSAGE pfnMessage);
507 ATECAT_API EC_T_VOID ecatPerfMeasDeinit( EC_T_TSC_MEAS_DESC* pTscMeasDesc );
508 ATECAT_API EC_T_VOID ecatPerfMeasEnable( EC_T_TSC_MEAS_DESC* pTscMeasDesc );
509 ATECAT_API EC_T_VOID ecatPerfMeasDisable( EC_T_TSC_MEAS_DESC* pTscMeasDesc );
510 ATECAT_API EC_T_VOID ecatPerfMeasStart( EC_T_TSC_MEAS_DESC* pTscMeasDesc, EC_T_DWORD dwIndex );
511 ATECAT_API EC_T_TSC_TIME* ecatPerfMeasEnd( EC_T_TSC_MEAS_DESC* pTscMeasDesc, EC_T_DWORD dwIndex );
512 ATECAT_API EC_T_VOID ecatPerfMeasReset( EC_T_TSC_MEAS_DESC* pTscMeasDesc, EC_T_DWORD dwIndex );
513 ATECAT_API EC_T_VOID ecatPerfMeasShow( EC_T_TSC_MEAS_DESC* pTscMeasDesc, EC_T_DWORD dwIndex, EC_T_CHAR** aszMeasInfo );
515 /*-COMPILER SETTINGS---------------------------------------------------------*/
516 #ifdef __cplusplus
517 } /* extern "C" */
518 #endif
520 #endif /* INC_ECEAP */
522 /*-END OF SOURCE FILE--------------------------------------------------------*/