DLL
Purpose
Interface with externally generated dynamic-link library
Library
Control / Functions & Tables
Description
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.
Platform | Filename search order |
Windows 32-bit | filename, filename.dll, filename_32.dll |
Windows 64-bit | filename, filename.dll, filename_64.dll |
Mac OS X 32-bit | filename, filename.dylib, filename_32.dylib |
Mac OS X 64-bit | filename, filename.dylib, filename_64.dylib |
Linux 32-bit | filename, filename.so, filename_32.so |
Linux 64-bit | filename, 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.