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 files

  • qgenpil wrapper* files

  • a file containing a symbol main, and for Ada, containing with and use clauses of each qgenpil wrapper

  • any 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:

  1. From the Simulink GUI

  2. From the MATLAB Command Line

  3. From the System Command Line

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 and c.

<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 either ada or c. If the --language switch is not provided, the tool will assume c.

  • --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 and for 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 and c. Defaults to c 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.