Processor in the loop (PIL) with QGen¶
Using qgenpil
¶
The code generated by QGen can be tested in the Simulink environment while
running on either an emulator or a real board (both referenced as target below)
using the executable qgenpil
.
qgenpil
generates an s-function for a given model that will be able to
communicate all the simulink input values to the target and retrieve the
computed outputs.
The executable running on the target has to be compiled manually for
the given architecture, with debug flags, from the following sources :
qgenc
*.c/*.{adb,ads} generated filesqgenpil
wrapper* filesa file containing a symbol
main
, and for Ada, containing with and use clauses of each qgenpil wrapperany other files ensuring a correct setup on the target
The communication between Simulink and the target is done using gdb. The requirement is to have a gdbserver running on the target and a (cross-)gdb on the host running Simulink.
State of the target¶
The gdbserver can be in one of two states when starting the PIL execution in Simulink:
The QGen executable is running and in a stopped state before the main symbol.
The QGen executable is in the target filesystem and no executable is running.
In that case the path of the executable on the target has to be specified in MATLAB using the
target_path
argument.
To generate the wrapper files and the Simulink S-Function that
communicates with the target you can invoke qgenpil
using 3 different
methods:
From the Simulink GUI
From the MATLAB Command Line
From the System Command Line
From the Simulink GUI¶
QGen PIL can be invoked from the Simulink user interface. This requires QGen to be correctly setup in MATLAB following the instructions in Setting up QGen in MATLAB.
The generation is launched from the window of a Simulink model by clicking on the QGen menu and then PIL.
The displayed fields are explained in Options for the S-Function generation.
Once the fields are filled accordingly, clicking on the generate button will create a model containing the S-function that will communicate with the target as specified.
From the MATLAB Command Line¶
QGen PIL can be invoked from the MATLAB command line using the
qgen_pil_build
function. This requires QGen to be correctly setup in MATLAB
following the instructions in Setting up QGen in MATLAB.
qgen_pil_build
has two required inputs and a number of optional parameters:
qgen_pil_build (<mdl_path>, <lang> [, <options>]);
mdl_path
Name of the mdl or slx file optionally with path (absolute or relative).
lang
Language matching the one of the QGenc source. Accepted values are
ada
andc
.
<options>
are all string values. Each option is either a single boolean
switch or a switch followed by a value. Options can be passed in an arbitrary
order.
Note
Options can be passed either as function arguments, or as a cell array of length 1 where the value of the first element is also a cell array containing the list of options.
Note
qgen_pil_build
should be called with the same switches than the qgen_build
call that generated source code from the model.
The available options are specified in Command line options.
Example :
qgen_pil_build ('test.mdl', 'ada', '-o', 'test_PIL')
From the System Command Line¶
qgenpil
is invoked on the system command line as follows:
qgenpil FILE [switches]
FILE
can be either a Simulink model file (.mdl or .slx) or a .xmi file
compliant with the Geneauto metamodel as available in
share/qgen/plugins/geneauto/geneauto.ecore
.
The following command lists all command line arguments supported by qgenpil
:
qgenpil --help
Note
qgenpil
should be called with the same switches than the qgenc
call
that generated source code from the model.
Mandatory Arguments¶
There are two mandatory arguments:
qgenpil FILE --pre-process-xmi [--language ada|c] [switches]
FILE
is the root model file exported in xmi format.
Language is not mandatory but HAS TO match the QGenc option for the targeted source code.
--language, -l VALUE
Specifies the language of the QGenc source.
VALUE
can be eitherada
orc
. If the--language
switch is not provided, the tool will assumec
.--pre-process-xmi
Mandatory argument to treat the root XMI file as one generated from MATLAB/Simulink Exporting the model information. QGenc accepts other XMI files as input that are a result of previous executions and do not require this argument.
Command line options¶
Input and Output Data¶
--output, -o DIR
Specifies an output directory for the generated code. If this argument is not specified, code is generated in
<FILE>_generated
by default. If the output directory is not empty, then one of the switches--clean
or--incremental
must be provided.--clean, -c
Instructs QGen to delete all the content of the output directory before starting the code generation.
--incremental, -i
Instructs QGen to leave the content of the output directory as is. Generated files will overwrite existing files with the same name, but other existing files will remain untouched.
When passing an .mdl or a .slx file, the following additional switches are available:
--matlab, -m FILE
Specifies a MATLAB file containing variable definitions that are used by the Simulink model. The MATLAB file must only contain variable definitions and not statements such as
if
andfor
constructs.--lib DIR
Specifies directories where library models can be found. The switch can be used multiple times to specify multiple directories.
Note
The --lib
switch is required only in case the relative location of
the libraries is different than at the time of export into XMI.
The new location given with the --lib
switch will override the original
location which is stored in the XMI.
MISRA Constraints Options¶
QGen automatically checks that the input model conforms to the MISRA Simulink constraints. The following flags control this check:
--no-misra
Disable checks for MISRA Simulink constraints.
--wmisra
Treat violations of MISRA Simulink as warnings.
Code Generation Options¶
--arith-conf
Specifies a file with transformations for arithmetic functions. See Customizing Arithmetic Functions.
--consts-as-vars
Generates all constants defined in .m files as variables.
--debug
Generate non-optimized code
--from-simulink
Indicates that
qgenpil
was executed from the MATLAB command line. This instructs QGen to produce block references in error messages as Simulink hyperlinks.--full-flattening
Specifies to flatten all non-virtual subsystems.
--ref-flattening
Flatten code for each model.
--global-io
Generates the function parameters of the main module as global variables in a separate module.
--no-jump
Removes goto statements.
--prettyprint NUM, -pp NUM
Format lines to be at most NUM characters long.
--remove-assertions
Remove code for assertion blocks and their inputs.
--noreuse-flattening
Use Simulink Function Packaging for subsystem code generation.
--subsys PATH
Generate code for the subsystem whose fully qualified name is
PATH
. For example--subsys MyModel/MySubsystem/AnotherSubsystem
.
Note
The selected block must be a Simulink subsystem. The option is not supported for Stateflow charts. However, the selected subsystem can contain Stateflow charts.
The selected Simulink subsystem can have a dedicated trigger or enable port (i.e. contain a Trigger or Enable block at the root level).
The selected Simulink subsystem must not have function call signals entering or leaving the subsystem’s boundary through other ports (i.e. input or output ports).
--wrap-io
Encapsulate formal parameters in Ada record types or C structs.
Options for the S-Function generation¶
When qgenpil
has finished a file s_func_<model>.m
is generated in the
output directory.
This MATLAB script needs to be launched to generate the S-function block that will communicate with the target.
Usage :
s_func_<model>(target_path, host_path, remote_addr, gdb_path, timeout, lang)
Note
All parameters are strings except for timeout which is an int
target_path
This parameter specifies the path on the target of the executable to run, if not necessary leave a dummy path (e.g
./a.out
) for more info State of the target.host_path
The path of the same executable than the one on the target on the Simulink machine, this is mandatory.
remote_addr
The address in the form <addr>:<port> used to connect to the gdbserver using a command similar to, this is mandatory :
target remote <remote_addr>
gdbpath
If a specific gdb has to be used (e.g. a cross-debugger) specify its global path here. Can be left empty, in that case the debugger used is the
gdb
in the path.timeout
Int value specifying the maximum time in seconds to wait for gdb to answer any request. Can be left empty, in that case the default timeout time is 8 seconds.
lang
Language matching the one of QGenc source. Accepted values are
ada
andc
. Defaults toc
if not set.
Executing the script should generate a model containing an s-function that will run the code according to the specified parameters.
Running the PIL S-Function¶
When you successfully generated the S-Function you can start your gdbserver on the target with the executable as specified here Using qgenpil. You can connect the S-Function input and output ports to any block to pass the values to the running executable and retrieve the computed outputs.
If the simulation does not start successfully make sure all the parameters you
specified for the S-Function are correct, if MATLAB was launched from the
command line you can check for [ERROR]
messages that can pinpoint the
error.