===================================== Processor in the loop (PIL) with QGen ===================================== .. _qgenpil_usage: 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. .. _qgenpil_gdbserver_status: 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 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 :ref:`qgen-setup-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 :ref:`qgenpil-s-function-options`. 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 :ref:`qgen-setup-in-matlab`. ``qgen_pil_build`` has two required inputs and a number of optional parameters: .. code-block:: text qgen_pil_build (, [, ]); * ``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``. ```` 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 :ref:`qgenpil_options`. Example : .. code-block:: text qgen_pil_build ('test.mdl', 'ada', '-o', 'test_PIL') From the System Command Line ============================ ``qgenpil`` is invoked on the system command line as follows: .. code-block:: text 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``: .. code-block:: text 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: .. code-block:: text 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 :ref:`exporting-model`. QGenc accepts other XMI files as input that are a result of previous executions and do not require this argument. .. _qgenpil_options: 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 ``_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 :ref:`arith-conf`. * ``--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. .. _qgenpil-s-function-options: Options for the S-Function generation ===================================== When ``qgenpil`` has finished a file ``s_func_.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 : .. code-block:: text s_func_(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 :ref:`qgenpil_gdbserver_status`. * ``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 : used to connect to the gdbserver using a command similar to, this is **mandatory** : .. code-block:: text target remote * ``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 :ref:`qgenpil_usage`. 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.