PLECS 3.3 Online Help

DLL

Purpose

Interface with externally generated dynamic-link library

Library

Control / Functions & Tables

Description

pict

The DLL block allows you to load a user generated DLL. The DLL may be implemented in any programming language on any development environment that the system platform supports. For convenience, all code snippets in this description are given in C.

The DLL must supply two functions, plecsSetSizes and plecsOutput. Additionally it may implement the functions plecsStart and plecsTerminate.

The complete DLL interface is described in the file include/plecs/DllHeader.h in the PLECS installation directory. This file should be included when implementing the DLL.

void plecsSetSizes(struct SimulationSizes* aSizes)

This function is called once during the initialization of a new simulation.

The parameter struct SimulationSizes is defined as follows:

struct SimulationSizes {
  int numInputs;
  int numOutputs;
  int numStates;
  int numParameters;
};

In the implementation of plecsSetSizes the DLL has to set all the fields of the supplied structure.

numInputs
The width of the input signal that the DLL expects. The length of the input array in the SimulationState struct is set to this value.
numOutputs
The number of outputs that the DLL generates. The width of the output signal of the DLL block and the length of the output array in the SimulationState struct is set to this value.
numStates
The number of discrete states that the DLL uses. The length of the states array in the SimulationState struct is set to this value.
numParameters
The length of the parameter vector that the DLL expects. A vector with numParameters elements must be supplied in the Parameters field of the component parameters of the DLL block. The parameters are passed in the parameters array in the SimulationState struct.

void plecsOutput(struct SimulationState* aState)

This function is called whenever the simulation time reaches a multiple of the Sample time of the DLL block.

The parameter struct SimulationState is defined as follows:

struct SimulationState {
  const double* const inputs;
  double* const outputs;
  double* const states;
  const double* const parameters;
  const double time;
  const char* errorMessage;
  void* userData;
};

inputs
The values of the input signal for the current simulation step. The values are read-only. The array length is the value of the numInputs field that was set in the plecsSetSizes method.
outputs
The output values for the current simulation step. These values must be set by the DLL. The array length is the value of the numOutputs field that was set in the plecsSetSizes method.
states
The values of the discrete states of the DLL. These values can be read and modified by the DLL. The array length is the value of the numStates field that was set in the plecsSetSizes method.
parameters
The values of the parameters that were set in the Parameters field in the component parameters of the DLL block. The values are read-only. The array length is the value of the numParameters field that was set in the plecsSetSizes method.
time
The simulation time of the current simulation step.
errorMessage
The DLL may indicate an error condition by setting an error message. The simulation will be stopped after the current simulation step.
userData
A pointer to pass data from one call into the DLL to another. The value is not touched by PLECS.

void plecsStart(struct SimulationState* aState)

This function is called once at the start of a new simulation. It may be used to set initial outputs or states, initialize internal data structures, acquire resources etc.

The values of the inputs array in the SimulationState struct are undefined in the plecsStart function.

void plecsTerminate(struct SimulationState* aState)

This function is called once when the simulation is finished. It may be used to free any resources that were acquired by the DLL.


Note  The processor architecture of the DLL must match the processor architecture of PLECS. If, for example, a 32-bit version of PLECS is used on a 64-bit Windows machine, a 32-bit DLL must be built. The processor architecture used by PLECS is displayed in the About PLECS ... dialog, accessible from the File menu.

Parameters

Filename
The filename of the DLL. If the filename does not contain the full path of the DLL, the DLL is searched relative to the directory containing the model file. If no DLL is found with the given filename, a platform specific ending will be attached to the filename and the lookup is retried. The endings and search order are listed in the table below.

PlatformFilename search order
Windows 32-bitfilename, filename.dll, filename_32.dll
Windows 64-bitfilename, filename.dll, filename_64.dll
Mac OS X 32-bitfilename, filename.dylib, filename_32.dylib
Mac OS X 64-bitfilename, filename.dylib, filename_64.dylib
Linux 32-bitfilename, filename.so, filename_32.so
Linux 64-bitfilename, filename.so, filename_64.so

Sample time
The simulation time interval between two successive calls to the output function of the DLL. See also the Discrete-Periodic sample time type in section Sample Times.
Output delay
Allows you to delay the output in each simulation step. This is useful when modeling, for example, a DSP that needs a certain processing time to calculate the new outputs. The output delay must be smaller than the sample time. If the output delay is a positive number, the DLL block has no direct feedthrough, i.e. its outputs can be fed back to its inputs without causing an algebraic loop.
Parameters
Array of parameter values to pass to the DLL. The length of the array must match the value of the numParameters field that the DLL sets in the plecsSetSizes method.

Probe Signals

Input
The input signal.
Output
The output signal.