MxVMC C/C++ API Reference Manual

When developing an MxVMC, you need to use the MxVDev Harness API to interface with the MxVDev test environment.

The Harness API is implemented in the MxVHarnessXX.lib. This library needs to be included in your build environment. The interface definitions and prototypes can be found in MxVHarness.h. The Library and header files are located in the MxVDev\Harness installation folder.

MxVDev provides libraries for several versions of Visual Studio. Be sure to link the correct one.

Visual Studio 2005 and earlier versions have been deprecated for MxSuite 3.36.45 and later.

Handler Functions

Many of the customizations you make as you build an MxVMC involve the use of Handler functions.

A Handler Function is invoked when there is a change in the Signal associated with it. You associate a Handler Function with a Signal by completing the ‘Handler Function Name’ field for the Signal in the Signal Dictionary.

API Reference

CurrentSigID

This variable is set by MxVDev prior to invoking a Handler function. It is a unique index of every signal given by MxVDev. You should not write to this variable. It should only be used as a parameter in calls like MxVGetSignalInfo(), MxVGetSignalValue(), and MxVGetMsgData() to get more information about a signal.

Note that during the execution of a scenario (for every signal handler invocation) a specific CurrentSigID will be associated with a given Signal. However, on re-executing a Scenario, the mapping of CurrentSigID to Signal may be different.

unsigned int CurrentSigID;

CurrentSigInd

A user-defined numeric value may be associated with any Signal by completing the Indicator (CurrentSigInd) field in the Signal Dictionary. The CurrentSigInd variable is set by MxVDev to the value defined in the Signal Dictionary just prior to invoking a Signal Handler function. It is normally used within the handler function to identify which signal has just changed.

For example, suppose you write a handler function called SigHndler, and in the Signal Dictionary you do the following:

Define Signal SigA, set its Handler Function to SigHndler, and its Indicator (CurrentSigInd) to 3.

Define Signal SigB, set its Handler Function to SigHndler, and its Indicator (CurrentSigInd) to 5.

Define Signal SigC, set its Handler Function to SigHndler, and its Indicator (CurrentSigInd) to 7.

Then within the Function SigHndler, you can know which signal just changed by checking the value of CurrentSigInd. If CurrentSigInd has a value of 3, then you know SigA just changed.

void * CurrentSigInd;

PortDefs

This array is defined in the default AppIF.c file. It may be used to communicate information about instrumented signals to MxVDev, however its original purpose has been largely superseded by enhanced Signal Dictionary capabilities.

You can make a signal available for use in a test case either by adding it to the Signal Dictionary, or by adding it to the PortDefs array. The definition of the type t_SigDesc in MxVHarness.h describes the use of each field in the PortDefs array.

const t_SigDesc PortDefs[];

TaskDefs

 

This array is defined in the default AppIF.c file. It may be used to communicate information about functions that can be invoked by MxVDev, however its original purpose has been largely superseded by enhanced Signal Dictionary capabilities.

You can make a function (task) available invoking from a test case either by adding it to the Signal Dictionary, or by adding it to the TaskDefs array. The definition of the type t_TaskDesc in MxVHarness.h describes the use of each field in the TaskDefs array.

const t_TaskDesc TaskDefs[];

Functions

Function

Description

MxVClose

This function is called whenever the SUT is unloaded, for example, when you reset the module, close the project, or close MxVDev.

void MxVClose(void);

MxVGetMsgData:

This function is used to get the current message data from a message type signal.

int MxVGetMsgData(unsigned int SigIndex, unsigned char ** pBuf, unsigned int * pLen);

Parameters:

SigIndex

[in] The ID of the Signal for which Name and Type are requested.

pBuf

[out] Address of a location to receive a pointer to the start of the message data.

pLen

[out] Address of a location to receive the length of the data in the message buffer

MxVGetScenario

This function returns a pointer to a string that stores the absolute path and file name of the current Scenario file.

char * MxVGetScenario(void);

MxVGetScenarioFolder

This function returns the default TestCase/Scenario folder from Project Settings

char * MxVGetScenarioFolder(void);

MxVGetSignalInfo

This function returns the name and type of the Signal referenced by SigIndex.

int MxVGetSignalInfo(unsigned int SigIndex, char ** pSigName, unsigned char * SigType);

Parameters:

SigIndex

[in] The ID of the signal for which Name and Type are requested.

pSigName

[out] The address of a character pointer variable. This variable will be set to point to a string containing the name of the Signal.

SigType

[out] Pointer to a character variable that receives the type of the Signal. Zero indicates that the Signal is numeric; one indicates that the Signal is a message.

MxVGetSignalValue

This function is used to get the value of a Signal whose type is numeric.

int MxVGetSignalValue(unsigned int SigIndex, unsigned int * pVal);

Parameters:

SigIndex

[in] The ID of the Signal for which Name and Type are requested.

pVal

[out] Pointer to an unsigned integer that receives the value of the Signal.

MxVGetSimulationTime

This function returns the MxVDev global time in nanoseconds as an unsigned 64-bit integer.

unsigned __int64 MxVGetSimulationTime(void);

MxVGetSUTPath

This function returns a pointer to a string that stores the absolute path and file name of the current SUT file.

char * MxVGetSUTPath(void);

MxVOpen

This function is called whenever an SUT is loaded.  (When a project is opened,  when the system signal MxV Module Reset is asserted, or when the SUT is loaded from the Main Menu  (Project->SUT->Reset and Project->SUT->Load))

void MxVOpen(void);

MxVRaiseErr

This function allows you to notify MxVDev that an error was detected in the Test Harness. MxVDev displays the error string to the user.

void MxVRaiseErr(char * ErrStr);

Parameters:

ErrStr

[in] A pointer to a string that describes the error that was detected.

MxVSendMsg

This function is used to transmit message data back to MxVDev.

int MxVSendMsg(char * pMsgName);

Parameters:

pMsgName

[in] A pointer to a string containing the name of the message in the Signal Dictionary

MxVSendMsgEx

The function to call when you want to notify the MxVDev test environment a message is sending.

int MxVSendMsgEx(char * pMsgName, unsigned int Len, mmuint32 Time_H, mmuint32 Time_L);

Parameters:

pMsgName

[in] A pointer to a string containing the name of the message in the Signal Dictionary

Len

[in] The length of the message data

Time_H

[in] The high part of the PC high resolution counter when the message is received

Time_L

[in] The low part of the PC high resolution counter when the message is received

MxVSendVariantLengthMsg

This function is used to transmit message data back to MxVDev.

int MxVSendVariantLengthMsg(char * pMsgName, unsigned int Len);

Parameters:

pMsgName

[in] A pointer to a string containing the name of the message in the Signal Dictionary

Len

[in] The length of current message data which may or may not be different from the definition of the message length, for example, CAN diagnostic message.

MxVSetScnStateFunction

This function sets up a callback function pointer in MxVDev. When the Scenario state changes the callback function id invoked.

void MxVSetScnStateFunction(void (__cdecl * pFunc)(e_ScnState ScnState))

Parameters:

ScnState

[in]ScnState The current execution state of the scenario. There are five Scenario states: Ready, Run, Pause, Rewind, and Complete.

MxVSoftwareReset

Queues a simulated software reset of the module. the current SUT Tick must exit before the reset will occur.

The SUT DLL is unloaded and reloaded identically to scheduling a Module Reset in a test-case.

Care should be taken in the SUT code to ensure the reset can occur seamlessly.

In particular, if a SUT_Init function is in use, it must be invoked after the reset.

Scheduling the SUT_Init from a test-case will not work properly as it unlikely to happen soon enough before a 'tick' occurs (or will not be reliable).

If the micro-controller emulation code is in place, then the initialization code can be integrated directly into the main function of the SUT.

If the SUT_Init function cannot easily be removed, then we recommend adding a flag that indicates SUT_Init has been executed. Then in the SUT_Tick function, check this flag and invoke SUT_Init if required.

void MxVSoftwareReset(void)

Related Topics:

Debugging SUT Applications Using MxVDev and Visual C++

Signal Dictionary