通过共享库进行时间同步¶
精确的时间同步对于测试结果的可靠性至关重要,尤其是在使用底层硬件工具和总线协议时。否则,超时或其他对时间敏感的功能可能无法正确应用。为了使总线通信和诊断通信能够基于外部时间源同步执行,可以为总线端口和诊断端口提供一个共享库(Windows 下为 DLL,Linux 下为 SO)。
该共享库必须满足以下接口:
Templates/DefaultData/Utilities/SharedLibs/UserSubscribe.h共享库头文件
信息
该共享库必须为目标平台构建为 64 位库。
/*******************************************************************
*
* FILENAME: UserSubcribe.h
*
* AUTHOR: tracetronic GmbH
*
* CREATED: 16.01.2024
*
* COPYRIGHT: Copyright © tracetronic GmbH, Dresden
*
* This file is distributed as an integral part of
* tracetronic's software products and may only be
* used in connection with and pursuant to the terms
* and conditions of a valid tracetronic software
* product license.
*
* Interface that provides the current time used by ecu.test
*
*******************************************************************/
#pragma once
#define VERSION 2
#ifdef MODELCLOCK_IMPORT
#define MODELCLOCK_API __declspec(dllimport)
#else
#define MODELCLOCK_API __declspec(dllexport)
#endif
#ifdef __cplusplus
extern "C"
{
#endif
#include <stdint.h>
#include <string.h>
#include <malloc.h>
// major, minor and patch version
typedef struct
{
uint32_t major;
uint32_t minor;
uint32_t patch;
} VersionInfo;
typedef struct
{
int32_t errorCode;
char *errorMessage;
} ModelClockError;
/**
* Type definition for the callback to update the clients model time (in nanoseconds).
*
* @param clientId The unique identifier of the client.
* @param time_ns The new model time in nanoseconds.
* @param error NULL if no error occurred. Otherwise pass a `ModelClockError` instance
* to signal the client the error. If error is present the time parameter
* is ignored.
* `ModelClockError_FromString` can be used to create a new `ModelClockError` instance.
*/
typedef void updateTimeFuncType(uint32_t clientId, uint64_t time_ns, ModelClockError *error);
/**
* Important:
* - This function has to be implemented by customers.
* - ecu.test might call exported functions from different threads,
* consequently they have to be implemented thread-safe.
*
* Initialization of the model clock for the calling client.
* This function is called once at the start of every client instance.
*
* @param[out] clientId Implementation has to return a unique client id via this pointer
* that identifies the calling client.
* This client id will be used by the client for subsequent function calls.
* @return If an error occurred return a `ModelClockError` instance, otherwise NULL.
* `ModelClockError_FromString` can be used to create a new `ModelClockError` instance.
*/
MODELCLOCK_API ModelClockError *ModelClock_Init(uint32_t *clientId);
/**
* Important:
* - This function has to be implemented by customers.
* - ecu.test might call exported functions from different threads,
* consequently they have to be implemented thread-safe.
*
* Deinitializes the model clock for the client instance identified by the given client id.
* This function is called once at the end of every client instance.
*
* @param clientId Unique client id that is used to identify the current client instance
* @return If an error occurred return a `ModelClockError` instance, otherwise NULL.
* `ModelClockError_FromString` can be used to create a new `ModelClockError` instance.
*/
MODELCLOCK_API ModelClockError *ModelClock_Close(uint32_t clientId);
/**
* Important:
* - This function has to be implemented by customers.
* - ecu.test might call exported functions from different threads,
* consequently they have to be implemented thread-safe.
*
* The client instance identified by the given client id subscribes the model clock.
* The client calls this function in order to stay up to date with respect to the model time.
* For that, the callback argument `updateTimeCallback` is passed and shall be called to
* update the clients model time (in nanoseconds).
* Basically, by calling `updateTimeCallback(...)`, the implementation tells the client
* the current model time (in nanoseconds).
*
* Example:
* ...
* // model time has changed => update clients model time
* uint64_t modelTime = ...;
* updateTimeCallback(clientId, modelTime, NULL);
* ...
*
* In addition, the implementation can inform the client of an occurred error:
*
* Example:
* ...
* // error occurred => inform the client
* ModelClockError *error = ModelClockError_FromString(-1, "Some error occurred :/");
* updateTimeCallback(clientId, 0, error);
* ...
*
* @param clientId Unique client id that is used to identify the current client instance
* @param[in] updateTimeCallback Callback for updating the clients model time
* @return If an error occurred return a `ModelClockError` instance, otherwise NULL.
* `ModelClockError_FromString` can be used to create a new `ModelClockError` instance.
*/
MODELCLOCK_API ModelClockError *ModelClock_SubscribeTime(uint32_t clientId, updateTimeFuncType *updateTimeCallback);
/**
* Important:
* - This function has to be implemented by customers.
* - ecu.test might call exported functions from different threads,
* consequently they have to be implemented thread-safe.
*
* The client instance identified by the given client id unsubscribes the model clock.
* If this function is called the implementation shall not call `updateTimeCallback()` for the given client id
* until `ModelClock_SubscribeTime()` has been called again.
*
* @param clientId Unique client id that is used to identify the current client instance
* @return If an error occurred return a `ModelClockError` instance, otherwise NULL.
* ` ModelClockError_FromString` can be used to create a new `ModelClockError` instance.
*/
MODELCLOCK_API ModelClockError *ModelClock_UnsubscribeTime(uint32_t clientId);
/**
* Important:
* - This function has to be implemented by customers.
* - ecu.test might call exported functions from different threads,
* consequently they have to be implemented thread-safe.
*
* Returns the version of the current DLL
* This is used for the purpose of logging the version of the used DLL
*
* @return The major, minor and patch version of the DLL
*/
MODELCLOCK_API VersionInfo ModelClock_GetDllVersionInfo();
/**
* Important: This function shall not be modified.
*
* Predefined function to return the version of the header.
*
* @return The major, minor and patch version of the header
*/
MODELCLOCK_API VersionInfo ModelClock_GetHeaderVersionInfo()
{
VersionInfo versionInfo = {1, 0, 0};
return versionInfo;
}
/**
* Predefined utility function to create a `ModelClockError` instance used by the API.
*
* Example:
* ModelClockError *modelError = ModelClockError_FromString(-1, "Some error :/");
*
* @param errorCode Error code of the occurred error. If no special error code is associated with the error,
* the default -1 is recommended.
* @param errorMessage A null-terminated error message for the occurred error.
* @return New `ModelClockError` instance
*/
static ModelClockError *ModelClockError_FromString(int32_t errorCode, const char *errorMessage)
{
size_t buffer_size = strlen(errorMessage) + 1;
if (buffer_size > 4000)
{
// avoid accidentally huge allocations
buffer_size = 4000;
}
char *errorMsgCopy = (char *)malloc(buffer_size);
if (!errorMsgCopy)
{
// should be academical
return NULL;
}
if (strcpy_s(errorMsgCopy, buffer_size, errorMessage) != 0)
{
// should be academical
return NULL;
}
ModelClockError *modelClockError = (ModelClockError *)malloc(sizeof(ModelClockError));
if (!modelClockError)
{
// should be academical
return NULL;
}
*modelClockError = ModelClockError{errorCode, errorMsgCopy};
return modelClockError;
}
#ifdef __cplusplus
}
#endif
为了保证完整功能,必须实现 ModelClock_Init、ModelClock_Close、ModelClock_SubscribeTime 和 ModelClock_UnsubscribeTime 方法。此外,也可以更新 ModelClock_GetDllVersionInfo 函数。
Example implementation(示例实现)¶
以下示例包含一个提供系统时间的实现。该文件可作为更复杂用例的起点。示例使用 C++ 编写,也可以使用 Rust、C 或 C# 等其他语言实现对应版本。
Templates/DefaultData/Utilities/SharedLibs/templateSubscribe.cppExample implementation(C++ 示例实现)
/*******************************************************************
*
* FILENAME: templateSubscribe.cpp
*
* AUTHOR: tracetronic GmbH
*
* CREATED: 16.01.2024
*
* COPYRIGHT: Copyright © tracetronic GmbH, Dresden
*
* This file is distributed as an integral part of
* tracetronic's software products and may only be
* used in connection with and pursuant to the terms
* and conditions of a valid tracetronic software
* product license.
*
* Example implementation that provides the system time used by ecu.test
*
*******************************************************************/
#include <atomic>
#include <chrono>
#include <mutex>
#include <list>
#include <random>
#include <thread>
#include "../../include/UserSubscribe.h"
typedef struct
{
uint32_t clientId;
updateTimeFuncType *updateTimeCallback;
} ClientSetting;
static std::mutex TIME_LOOP_LOCK;
static std::list<ClientSetting> subscribedClients = {};
static bool initializedRandomness = false;
static std::mt19937 rng;
static uint64_t get_time_ns()
{
auto time_point = std::chrono::system_clock::now();
return std::chrono::time_point_cast<std::chrono::nanoseconds>(time_point).time_since_epoch().count();
}
static uint32_t generate_id()
{
if (!initializedRandomness)
{
std::random_device rd;
rng.seed(rd());
initializedRandomness = true;
}
return rng();
}
static void time_loop_thread(updateTimeFuncType *updateTimeCallback)
{
while (1)
{
std::this_thread::sleep_for(std::chrono::milliseconds(10));
{
std::lock_guard<std::mutex> guard(TIME_LOOP_LOCK);
if (subscribedClients.empty())
{
return;
}
auto time = get_time_ns();
for (auto clientSetting : subscribedClients)
{
clientSetting.updateTimeCallback(clientSetting.clientId, time, NULL);
}
}
}
}
/*******************************************************************
* Public C Functions
*******************************************************************/
ModelClockError *ModelClock_Init(uint32_t *clientId)
{
std::lock_guard<std::mutex> guard(TIME_LOOP_LOCK);
*clientId = generate_id();
return NULL;
}
ModelClockError *ModelClock_Close(uint32_t clientId)
{
return NULL;
}
ModelClockError *ModelClock_SubscribeTime(uint32_t clientId, updateTimeFuncType *updateTimeCallback)
{
std::lock_guard<std::mutex> guard(TIME_LOOP_LOCK);
auto initialTime = get_time_ns();
updateTimeCallback(clientId, initialTime, NULL);
bool startLoop = subscribedClients.empty();
ClientSetting setting = ClientSetting{clientId, updateTimeCallback};
subscribedClients.push_back(setting);
if (startLoop)
{
std::thread(time_loop_thread, updateTimeCallback).detach();
}
return NULL;
}
ModelClockError *ModelClock_UnsubscribeTime(uint32_t clientId)
{
std::lock_guard<std::mutex> guard(TIME_LOOP_LOCK);
subscribedClients.remove_if([clientId](ClientSetting setting)
{ return setting.clientId == clientId; });
return NULL;
}
VersionInfo ModelClock_GetDllVersionInfo()
{
VersionInfo versionInfo = {0, 1, 0};
return versionInfo;
};