通过共享库进行时间同步

精确的时间同步对于测试结果的可靠性至关重要,尤其是在使用底层硬件工具和总线协议时。否则,超时或其他对时间敏感的功能可能无法正确应用。为了使总线通信和诊断通信能够基于外部时间源同步执行,可以为总线端口和诊断端口提供一个共享库(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.cpp Example 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;
};