SimMock API Reference

SimMock API

The SimMock API provides interfaces for the development of CMocka Tests with a representative mocked implementation of the ModelC <-> SimBus interface. The mock supports a Signal Vector (scalar) and Network Vector (binary). Several models may be loaded into the SimMock.

Component Diagram

@startuml simmock-objects

title SimMock Objects

package "SimBus Mock" {
    class Signal <<SignalVector>> {
        +uint32_t count
        +double scalar[]
        +annotation()
    }

    class Network <<SignalVector>> {
        +uint32_t count
        +bool is_binary
        +void* binary[]
        #NCODEC* ncodec[]
        +annotation()
        +append()
        +reset()
        #codec()
    }

    file svSig [
    signalgroup.yaml
    ....
    kind: <b>SignalGroup
    metadata:
    name: <b>signal
    labels:
        channel: <b>signal_vector
    ]

    file svNet [
    signalgroup.yaml
    ....
    kind: <b>SignalGroup
    metadata:
    name: <b>network
    labels:
        channel: <b>network_vector
    annotations:
        vector_type: <b>binary
    ]

    Signal -> svSig
    Network -> svNet
}

map ModelMock {
    sv_signal *--> Signal
    sv_network *--> Network
}

map SimMock {
    model *--> ModelMock

    sv_signal *--> Signal
    sv_network_rx *-> Network
    sv_network_tx *-> Network
}

center footer Dynamic Simulation Environment

@enduml

Typedefs

BinaryCheck

typedef struct BinaryCheck {
    int index;
    int* buffer;
    int len;
}

FrameCheck

typedef struct FrameCheck {
    int frame_id;
    int offset;
    int value;
    bool not_present;
}

ModelMock

typedef struct ModelMock {
    const char* name;
    int* mi;
    int* sv_signal;
    int* sv_network;
    int* sv_save;
    int vtable;
    int* sm_signal;
    int* mfc_signal;
}

SignalCheck

typedef struct SignalCheck {
    int index;
    double value;
}

SimMock

typedef struct SimMock {
    int sim;
    double step_size;
    ModelMock* model;
    void* doc_list;
    double model_time;
    int* sv_signal;
    int* sv_network_rx;
    int* sv_network_tx;
}

Functions

simmock_alloc

Create a SimMock object.

Parameters

inst_names[] (const char*): Array of model instance names which should be allocated in the SimMock object.
count (size_t): The number of elements in the inst_names array.

Returns

SimMock*: The allocated SimMock object. Caller should free by calling simmock_free().

simmock_binary_check

Check the content of a binary signal.

Parameters

mock (SimMock*): A SimMock object.
model_name (const char*): The name of the model to check.
checks (BinaryCheck*): Array of BinaryCheck objects.
count (size_t): The number elements in the checks array.
func (BinaryCheckFunc): Optional function pointer for performing the binary check.

simmock_configure

Configure a SimMock object with a list of command line arguments (as would be used by the ModelC.exe).

Example

#include <dse/testing.h>
#include <dse/mocks/simmock.h>

int test_setup(void** state)
{
    const char* inst_names[] = {
        "target_inst",
        "network_inst",
    };
    char* argv[] = {
        (char*)"test_runnable",
        (char*)"--name=target_inst;network_inst",
        (char*)"--logger=5",  // 1=debug, 5=QUIET (commit with 5!)
        (char*)"../../../../tests/cmocka/network/stack.yaml",
        (char*)"../../../../tests/cmocka/network/signalgroup.yaml",
        (char*)"../../../../tests/cmocka/network/network.yaml",
        (char*)"../../../../tests/cmocka/network/model.yaml",
        (char*)"../../../../tests/cmocka/network/runnable.yaml",
    };
    SimMock* mock = simmock_alloc(inst_names, ARRAY_SIZE(inst_names));
    simmock_configure(mock, argv, ARRAY_SIZE(argv), ARRAY_SIZE(inst_names));
    simmock_load(mock);
    simmock_setup(mock, "signal", "network");

    /* Return the mock. */
    *state = mock;
    return 0;
}

Parameters

mock (SimMock*): A SimMock object.
argv (char*): Array of arguments.
argc (size_t): Number of elements in the argv array.
expect_model_count (size_t): The expected number of models to be configured (based on the parsed list of arguments).

simmock_exit

Call model_destroy() for each model.

Parameters

mock (SimMock*): A SimMock object.
call_destroy (bool): Indicate that model_destroy() should be explicitly called. Set to true when using the SimMock library outside of the ModelC repo (which has its own mock object representing the controller).

simmock_find_model

Find a MockModel object contained within a SimMock object.

Parameters

mock (SimMock*): A SimMock object.
name (const char*): The name of the model to find.

Returns

MockModel*: The identified MockModel object.
NULL: No MockModel was found.

simmock_frame_check

Check the content of a binary signal for various frames. The binary signal should be represented by a Network Codec (NCodec) object.

Example

#include <dse/testing.h>
#include <dse/mocks/simmock.h>

void test_network__frame_check(void** state)
{
    SimMock* mock = *state;

    /* 0ms - initial tick, Rx consumed, Tx of initial content. */
    {
        for (uint32_t i = 0; i < 1; i++) {
            assert_int_equal(simmock_step(mock, true), 0);
        }
        FrameCheck f_checks[] = {
            { .frame_id = 0x1f3u, .offset = 0, .value = 0x01 },
            { .frame_id = 0x1f4u, .offset = 1, .value = 0x02 },
            { .frame_id = 0x1f5u, .offset = 4, .value = 0x02 },
        };
        simmock_print_network_frames(mock, LOG_DEBUG);
        simmock_frame_check(
            mock, "network_inst", "can_bus", f_checks, ARRAY_SIZE(f_checks));
    }
}

Parameters

mock (SimMock*): A SimMock object.
model_name (const char*): The name of the model to check.
sig_name (const char*): The name of the binary signal where frames should be located.
checks (FrameCheck*): Array of FrameCheck objects.
count (size_t): The number elements in the checks array.

simmock_free

Destroy and free resources allocated to a SimMock object.

Parameters

mock (SimMock*): The SimMock object to be released.

simmock_load

Load all of the models referenced by a SimMock object.

Parameters

mock (SimMock*): A SimMock object.

simmock_load_model_check

Check the condition/state of a loaded model.

Parameters

mock (SimMock*): A SimMock object.
expect_create_func (bool): Indicate that model libraries should contain a model_create function.
expect_step_func (bool): Indicate that model libraries should contain a model_step function.
expect_destroy_func (bool): Indicate that model libraries should contain a model_destroy function.

simmock_print_binary_signals

Print the binary signals contained in each network vector of each model.

Parameters

mock (SimMock*): A SimMock object.
level (int): The log level to print at.

simmock_print_network_frames

Print the frames contained in each network vector of each model.

Parameters

mock (SimMock*): A SimMock object.
level (int): The log level to print at.

simmock_print_scalar_signals

Print the scalar signal values of each signal vector of each model.

Parameters

mock (SimMock*): A SimMock object.
level (int): The log level to print at.

simmock_read_frame

Read a frame, using the associated NCodec object, from the specified binary signal.

Parameters

sv (SignalVector*): A Signal Vector object.
sig_name (const char*): The name of the binary signal where frames should be written.
data (uint8_t*): Array for the read data. The data is preallocated by the caller.
len (size_t): Length of the data array.

Returns

uint32_t: The Frame ID associated with the read data.
0: No frame was found in the specified binary signal.

simmock_setup

Calls the model_setup() function on each model and then creates Signal Vectors for each model. Additional Signal Vectors are created to facilitate the mocked behaviour of a simulation (via the SimMock object).

Parameters

mock (SimMock*): A SimMock object.
sig_name (const char*): The name of the scalar channel.
sig_name (const char*): The name of the binary channel.

simmock_signal_check

Check the values of various signals on the Signal Vector (scalar).

Example

#include <dse/testing.h>
#include <dse/mocks/simmock.h>

#define SIG_task_init_done 1
#define SIG_task_5_active  2
#define SIG_task_5_counter 6

void test_network__signal_check(void** state)
{
    SimMock* mock = *state;

    /* 0ms - initial tick, Rx consumed, Tx of initial content. */
    {
        for (uint32_t i = 0; i < 1; i++) {
            assert_int_equal(simmock_step(mock, true), 0);
        }
        SignalCheck s_checks[] = {
            { .index = SIG_task_init_done, .value = 1.0 },
            { .index = SIG_task_5_active, .value = 0.0 },
            { .index = SIG_task_5_counter, .value = 0.0 },
        };
        simmock_print_scalar_signals(mock, LOG_DEBUG);
        simmock_signal_check(
            mock, "network_inst", s_checks, ARRAY_SIZE(s_checks), NULL);
    }
}

Parameters

mock (SimMock*): A SimMock object.
model_name (const char*): The name of the model to check.
checks (SignalCheck*): Array of SignalCheck objects.
count (size_t): The number elements in the checks array.
func (SignalCheckFunc): Optional function pointer for performing the signal check.

simmock_step

Calls model_step() on each model and manages the mocked exchange of both scalar and binary Signal Vectors.

Parameters

mock (SimMock*): A SimMock object.
assert_rc (bool): Indicate that an assert check (value 0) should be made for each return from a call to model_step().

Returns

int: The combined (or’ed) return code of each call to model_step().

simmock_write_frame

Write a frame, using the associated NCodec object, to the specified binary signal.

Parameters

sv (SignalVector*): A Signal Vector object.
sig_name (const char*): The name of the binary signal where frames should be written.
data (uint8_t*): Array of data to write (in the frame).
len (size_t): Length of the data array.
frame_id (uint32_t): The Frame ID associated with the data.
frame_type (uint8_t): The Frame Type associated with the frame.