5. QGen Model Debugger

5.1. Requirements and installation

The QGen Debugger is a built-in add-on for QGen. You will have to proceed with the QGen installation before installing the QGen debugger, see Installing QGen.

The QGen Debugger package contains multiple tools including a compiler and a debugger that are not intended to be used independently from the QGen Debugger and are not supported outside of that usage.

To proceed with the installation of QGen Debugger, follow the same instructions as for QGen in Installing QGen. Choose the QGen installation folder $QGEN_INSTALL as the installation directory.

Then, to use QGen Debugger from your MATLAB environment, follow the setup process in Setting up QGen in MATLAB.

5.4. Generating code and starting a debugging session

Once the project is successfully loaded inside GNAT Studio you should see the following icons:

_images/GPS_Toolbar.png

The left one will generate code using qgenc and the options specified inside the project file and then compile the executable using the generated code and any additional source file provided by the project file.

The right icon will compile like the left one but will also start a debugging session.

If you do not wish to generate code, but still need to build your executable and/or debug the model you can use the GNAT Sutdio menus Build > Project > Build all and Debug > Initialize > [project_name] > main.[c|adb].

If you open the model by double cliking on it gps will load it and open it in a new view, displaying all the blocks and signals (cf. image below)

_images/model_view.png

5.4.1. Editing QGen code generation options

To edit the options that QGen uses for code generation, there are two options:

5.4.1.1. Graphically

In the Project View, right-click on the XMI file that corresponds to the top-level model of the project (e.g. speedometer.xmi), then click on Edit switches for speedometer.xmi.

A configuration dialog will open. You may select options graphically or edit the command-line at the bottom. Clicking on Save will apply those switches to the XMI file and automatically update the project.

5.4.1.2. Editing the project source file

Alternatively, you may open the project source file and edit it. Right-click on the project in the Project View, Project -> Edit source file, then edit the following line to use the desired code generation options:

for Switches ("speedometer.xmi") use ("--debug", "-l", "c", "--pre-process-xmi", "--gen-entrypoint");

Do not forget to reload the project after saving the file.

5.5. QGen Debugger features

Once the debugger has started you can right click in the model view to display a contextual menu giving you access to the model debugging features.

_images/debugger_contextual.png

In the contextual menu hover on the Debug submenu to choose between the following options during debugging session

  1. Show the current execution pointer in the source code
  2. Set/Delete a breakpoint on the block (the corresponding breakpoints will be set or deleted inside the generated source code at the lines corresponding to the chosen block).
  3. Change the value of a signal to alter the corresponding variable value in the code by clicking on Set Value for signal. This is really valuable to force a model to reach a certain stage and test it with a variety of values. You can force a signal to stay at a given value by checking the Peristent box and enter the desired value in the dialog box. This will preserve the value set over the program iterations to force specific cases to happen, which is a powerful way to test behaviours that are difficult to construct from the top level inputs.
  4. In the Models submenu the Show source code action will show the block corresponding source code in the generated source file.

During the execution the model view is also updated to show the current block under execution with a green outline, and the value for all the signals in the current subsystem. Some signal values will not be up to date at some point during the execution but you can refer to the source code to find out where this is the case.

_images/debugger_execution.png

You can navigate between subsystems by double clicking on a subsystem or using the Uparrow and LeftArrow buttons above the diagram to navigate to the parent or previous subsystem respectively. The model hierarchy is also represented in the outline panel when the diagram is under focus, and you can click on a subsystem to visit it. All current blocks from the current subsystem are also listed in the outline panel, clicking on a block will highlight item.

_images/debugger_outline.png

All signals values are updated when the displayed subsystem changes.

5.5.1. QGen Debugger constraints

5.5.1.1. Stateflow charts

QGen Debugger only displays Stateflow Chart Blocks. They cannot be opened to display their internal events, states or transitions, and the debugging support is limited to setting breakpoints on the entry point of a chart.

5.6. Advanced usage

5.6.1. Use a separate compiler/debugger/{GNAT Studio|GPS} version

You might be interested in using a different version of the tools packaged with the QGen Debugger. This is possible but please be aware that some features of the debugger might not work with older versions of the tools.

To specify which tools to use when launching {GNAT Studio|GPS} and the QGen debugger from MATLAB you must edit the file etc/qgen_tools.env in the QGen installation path. You can either add each necessary environment variable manually or on Unix*, simply run env >> etc/qgen_tools.env from your terminal.

To change the compiler/debugger within {GNAT Studio|GPS} go to Build > Settings > Toolchains and edit the Compiler path and Tools path as necessary.