RAS-Server for EC-Lyser and EC-Engineer

3.7. RAS-Server for EC-Lyser and EC-Engineer

3.7.1. Integration Requirements

To use the diagnosis tool EC-Lyser with a customer application, some modifications have to be done during integration of the EC-Simulator. The task is to integrate and start the Remote API Server system within the custom application, which provides a socket based uplink, which later on is connected by the EC-Lyser.

Diagram showing RAS-Server integration requirements with EC-Lyser or EC-Engineer connecting via a socket-based uplink to the Remote API (RAS) Server opened by the customer application for EC-Simulator diagnosis

An example on how to integrate the Remote API Server within the application is given with the example application EcSimulatorHilDemo, which is preconfigured to listen for EC-Lyser on TCP Port 6000 when command line parameter “-sp” is given.

To demonstrate the steps needed within a custom application, a developer may use the following pseudo-code segment as a point of start. The Remote API Server library “EcSimulatorRasServer” must be linked.

3.7.2. Pseudo Code

#include "EcSimulatorRasServer.h"

/* custom Remote API Notification handler, example in EcSimulatorHilDemo (EcNotification.cpp) */
EC_T_DWORD RasNotifyCallback(
    EC_T_DWORD          dwCode,     /**< [in]   Notification code identifier */
    EC_T_NOTIFYPARMS*   pParms      /**< [in]   Notification data portion */
                    )
{
    /* custom notification handler */
}

    /* initialization  */
    EC_T_RAS_SERVER_PARMS  oRemoteApiConfig;
    OsMemset(&oRemoteApiConfig, 0, sizeof(EC_T_RAS_SERVER_PARMS));
    EC_T_PVOID          pvRemApiHandle;
    oRemoteApiConfig.dwSignature            = EC_RAS_SERVER_SIGNATURE;
    oRemoteApiConfig.dwSize                 = sizeof(EC_T_RAS_SERVER_PARMS);
    /* INADDR_ANY */
    oRemoteApiConfig.oAddr.dwAddr           = 0;
    /*< default is port 6000 > */
    oRemoteApiConfig.wPort                  = wServerPort;
    /*< default is 2 ms */
    oRemoteApiConfig.dwCycleTime            = EC_RAS_CYCLE_TIME;
    oRemoteApiConfig.dwCommunicationTimeout = EC_RAS_MAX_WATCHDOG_TIMEOUT;
    EC_CPUSET_ZERO(oRemoteApiConfig.oAcceptorThreadCpuAffinityMask);
    oRemoteApiConfig.dwAcceptorThreadPrio           = MAIN_THREAD_PRIO;
    oRemoteApiConfig.dwAcceptorThreadStackSize      = JOBS_THREAD_STACKSIZE;
    EC_CPUSET_ZERO(oRemoteApiConfig.oClientWorkerThreadCpuAffinityMask);
    oRemoteApiConfig.dwClientWorkerThreadPrio       = MAIN_THREAD_PRIO;
    oRemoteApiConfig.dwClientWorkerThreadStackSize  = JOBS_THREAD_STACKSIZE;
    /* RAS notification callback function */
    oRemoteApiConfig.pfnRasNotify     = RasNotifyCallback;
    /* RAS notification callback function context */
    oRemoteApiConfig.pvRasNotifyCtxt = pAppContext->pNotificationHandler;
    /* pre-allocation */
    oRemoteApiConfig.dwMaxQueuedNotificationCnt = 100;
    /* pre-allocation */
    oRemoteApiConfig.dwMaxParallelMbxTferCnt       = 50;
    /* span between to consecutive cyclic notifications of same type */
    oRemoteApiConfig.dwCycErrInterval              = 500;

    /* init simulator */
    esInitSimulator(...);

    /* start remote API server */
    esRasSrvStart(dwSimulatorInstanceId, &oRemoteApiConfig, &pvRemApiHandle);

    /* stop remote API server */
    esRasSrvStop(dwSimulatorInstanceId, pvRemApiHandle, 2000)

    esDeinitSimulator(...);
}

3.7.3. Required API Calls

3.7.3.1. esRasSrvStart

EC_T_DWORD EC_NAMESPACE::esRasSrvStart(const EC_T_RAS_SERVER_PARMS *pParms, EC_T_PVOID *ppHandle)

Starts the RAS Server.

Parameters:

  • pParms – [in] Server start-up parameters

  • ppHandle – [out] Handle to opened instance, used for ctrl access

Returns:

EC_E_NOERROR or error code

struct EC_T_RAS_SERVER_PARMS

Public Members

EC_T_DWORD dwSignature

[in] Set to EC_RAS_SERVER_SIGNATURE

EC_T_DWORD dwSize

[in] Set to sizeof(EC_T_RAS_SERVER_PARMS)

EC_T_LOG_PARMS LogParms

[in] Logging parameters

EC_T_IPADDR oAddr

[in] Remote Access Server (RAS) listen IP address

EC_T_WORD wPort

[in] Remote Access Server (RAS) listen port

EC_T_WORD wMaxClientCnt

[in] Max. clients in parallel (0: unlimited)

EC_T_DWORD dwCycleTime

[in] Cycle Time of RAS Network access (acceptor, worker)

EC_T_DWORD dwCommunicationTimeout

[in] Timeout [ms] before automatically closing connection

EC_T_CPUSET oAcceptorThreadCpuAffinityMask

[in] Acceptor Thread CPU affinity mask

EC_T_DWORD dwAcceptorThreadPrio

[in] Acceptor Thread Priority

EC_T_DWORD dwAcceptorThreadStackSize

[in] Acceptor Thread Stack Size

EC_T_CPUSET oClientWorkerThreadCpuAffinityMask

[in] Client Worker Thread CPU affinity mask

EC_T_DWORD dwClientWorkerThreadPrio

[in] Client Worker Thread Priority

EC_T_DWORD dwClientWorkerThreadStackSize

[in] Client Worker Thread Stack Size

EC_T_DWORD dwMaxQueuedNotificationCnt

[in] Amount of concurrently queue able Notifications

EC_T_DWORD dwMaxParallelMbxTferCnt

[in] Amount of concurrent active mailbox transfers

EC_PF_NOTIFY pfnRasNotify

[in] Function pointer called to notify error and status information generated by Remote API Layer

EC_T_VOID *pvRasNotifyCtxt

[in] Notification context returned while calling pfNotification

EC_T_DWORD dwCycErrInterval

[in] Interval which allows cyclic Notifications

EC_T_DWORD dwMaxQueuedNotificationSize

[in] Size of concurrent active mailbox transfers

EC_PF_CHECK_TOKEN pfCheckToken

[in] Function pointer called to check token

EC_T_VOID *pvCheckTokenContext

[in] Check token context

EC_T_BYTE *pbyTlsCert

[in] TLS certificate filename string

EC_T_DWORD dwTlsCertSize

[in] Size of TLS certeficate

EC_T_TLS_CERT_TYPE eTlsCertType

[in] TLS certeficate type

EC_T_BYTE *pbyTlsPrivKey

[in] TLS private key filename string

EC_T_DWORD dwTlsPrivKeySize

[in] Size of TLS private key

EC_T_TLS_PRIVKEY_TYPE eTlsPrivKeyType

[in] TLS certeficate type

union EC_T_IPADDR
#include <EthernetServices.h>

Public Members

EC_T_INNER_IPADDR sAddr

IPv4 address (endianness independent)

EC_T_DWORD dwAddr

Reserved, use EC_T_IPADDR::sAddr.by instead. OS-Layer socket API calls (SOCKADDR_IN::sin_addr).

struct EC_T_INNER_IPADDR

Public Members

EC_T_BYTE by[4]

IPv4 address (endianness independent)

3.7.3.2. esRasSrvStop

EC_T_DWORD EC_NAMESPACE::esRasSrvStop(EC_T_PVOID pvHandle, EC_T_DWORD dwTimeout)

Stops the RAS Server.

Parameters:

  • pvHandle – [in] Handle to previously started Server

  • dwTimeout – [in] Timeout [ms] used to shut down all spawned threads, it’s multiplied internally by the amount of threads spawned

Returns:

EC_E_NOERROR or error code

3.7.3.3. RasNotifyCallback - xxx

Callback function called by Remote API Server in case of State changes or error situations.

Data structure filled with detailed information about the according notification.

struct EC_T_NOTIFYPARMS
EC_T_VOID *pCallerData
EC_T_BYTE *pbyInBuf
EC_T_DWORD dwInBufSize
EC_T_BYTE *pbyOutBuf
EC_T_DWORD dwOutBufSize
EC_T_DWORD *pdwNumOutData

3.7.3.4. RasNotifyCallback - EC_RAS_NOTIFY_CONNECTION

Notification about a change in the Remote API’s state.

RasNotifyCallback - EC_RAS_NOTIFY_CONNECTION
Parameter

  • pbyInBuf: [in] Pointer to data of type EC_T_RAS_CONNOTIFYDESC

  • dwInBufSize: [in] Size of the input buffer in bytes

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

Data structure containing the new Remote API state and the cause of state change.

struct EC_T_RAS_CONNOTIFYDESC

Public Members

EC_T_DWORD dwCause

[in] Cause of state connection state change

EC_T_DWORD dwCookie

[in] Unique identification cookie of connection instance

3.7.3.5. RasNotifyCallback - EC_RAS_NOTIFY_REGISTER

Notification that a connected application registered a client to the stack.

RasNotifyCallback - EC_RAS_NOTIFY_REGISTER
Parameter

  • pbyInBuf: [in] Pointer to data of type EC_T_RAS_REGNOTIFYDESC

  • dwInBufSize: [in] Size of the input buffer in bytes

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

struct EC_T_RAS_REGNOTIFYDESC

Public Members

EC_T_DWORD dwCookie

[in] Unique identification cookie of connection instance

EC_T_DWORD dwResult

[in] Result of registration request

EC_T_DWORD dwInstanceId

[in] Master Instance client registered to

EC_T_DWORD dwClientId

[in] Client ID of registered client

3.7.3.6. RasNotifyCallback - EC_RAS_NOTIFY_UNREGISTER

Notification that a connected application un-registered a client from the simulator stack.

RasNotifyCallback - EC_RAS_NOTIFY_UNREGISTER
Parameter

  • pbyInBuf: [in] Pointer to data of type EC_T_RAS_REGNOTIFYDESC

  • dwInBufSize: [in] Size of the input buffer in bytes

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

RasNotifyCallback - EC_RAS_NOTIFY_REGISTER

3.7.3.7. RasNotifyCallback - EC_RAS_NOTIFY_MARSHALERROR

Notification about an error during marshalling in Remote API Server connection layer.

RasNotifyCallback - EC_RAS_NOTIFY_MARSHALERROR
Parameter

  • pbyInBuf: [in] Pointer to data of type EC_T_RAS_MARSHALERRORDESC

  • dwInBufSize: [in] Size of the input buffer in bytes

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

struct EC_T_RAS_MARSHALERRORDESC

Public Members

EC_T_DWORD dwCookie

[in] Unique identification cookie of connection instance

EC_T_DWORD dwCause

[in] Cause of the command marshalling error

EC_T_DWORD dwLenStatCmd

[in] Length of the faulty command

EC_T_DWORD dwCommandCode

[in] Command code of the faulty command

3.7.3.8. RasNotifyCallback - EC_RAS_NOTIFY_ACKERROR

Notification about an error during creation of ack / nack packet.

RasNotifyCallback - EC_RAS_NOTIFY_ACKERROR
Parameter

  • pbyInBuf: [in] Pointer to EC_T_DWORD containing error code

  • dwInBufSize: [in] Size of the input buffer in bytes

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

3.7.3.9. RasNotifyCallback - EC_RAS_NOTIFY_NONOTIFYMEMORY

Notification given, when no empty buffers for notifications are available in pre-alloced notification store. This points to a configuration error.

RasNotifyCallback - EC_RAS_NOTIFY_NONOTIFYMEMORY
Parameter

  • pbyInBuf: [in] Pointer to EC_T_DWORD containing a unique identification cookie of connection instance

  • dwInBufSize: [in] Size of the input buffer in bytes

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

3.7.3.10. RasNotifyCallback - EC_RAS_NOTIFY_STDNOTIFYMEMORYSMALL

Notification given when the buffer size for standard notifications available in pre-alloced notification store is too small to carry a specific notification. This points to a configuration error.

3.7.3.11. RasNotifyCallback - EC_RAS_NOTIFY_MBXNOTIFYMEMORYSMALL

Notification given when the buffer size for Mailbox notifications available in pre-alloced notification store is too small to carry a specific notification. This points to a configuration error.

RasNotifyCallback - EC_RAS_NOTIFY_MBXNOTIFYMEMORYSMALL
Parameter

  • pbyInBuf: [in] Pointer to EC_T_DWORD containing unique identification cookie of connection instance

  • dwInBufSize: [in] Size of the input buffer in bytes

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

This is a serious error. If this error occurs, Mailbox Transfer objects may have gotten out of sync and are therefore no longer valid.

See also

esRasSrvStart() for Mailbox notifications should be dimensioned correctly.