.. _constraints: ################################ QGen Constraints on Input Models ################################ Simulink Version ================ The QGen toolset is compatible with MATLAB and Simulink versions R2015b and newer. Simulink Block Types and Constraints ==================================== This section lists the Simulink block types supported by QGen and details the constraints under which they are supported. This information is organised in the following sections: * :ref:`alpha-list` * :ref:`lib-list` * :ref:`block-cst` .. _alpha-list: Supported Simulink Block Types (alphabetically) ----------------------------------------------- .. include:: generated/blocklist.rst.inc .. _lib-list: Supported Simulink Block Types (by library) ------------------------------------------- .. include:: generated/liblist.rst.inc .. _block-cst: Simulink Block Constraints -------------------------- .. include:: generated/constraintlist.rst.inc Additional Simulink Block Constraints ------------------------------------- S-functions and Legacy Code ~~~~~~~~~~~~~~~~~~~~~~~~~~~ See :ref:`legacy-code`. Lookup and Interpolation Blocks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The blocks where interpolation or lookup table are given by input port (Lookup Table Dynamic, Prelookup,Interpolation Using Prelookup) can not appear in a model where the table data is received from a top-level input. This includes models referenced by Model Reference block. Other Simulink Constraints ========================== Model Configuration Parameters ------------------------------ Solver ~~~~~~ Solver type should be discrete, fixed-step. Diagnostics ~~~~~~~~~~~ Model Initialization must be set to "Simplified" or, if it is set to "Classic", then "Detect multiple driving blocks executing at the same time step" must be set to "error". Blocks Configuration -------------------- All blocks should have sample time set to "inherited", except in the case of non-directfeedthrough blocks (UnitDelay, DiscreteTimeIntegrator, ...). Signal Dimensions ------------------ Scalar, vectors and two-dimensional matrices are supported. Matrices with more dimensions are not supported. Custom Data Types ------------------ It is possible to generate code with externally declared datatypes. See :ref:`custom-data-types` for the details. Use of Callback Functions ------------------------- Simulink allows adding callback functions to models, blocks or port. These functions may be there just for documentation purposes. QGenc does not support callbacks functions. It is up to the user to verify they are not present or, if present, they do not affect the model behaviour. **NB!** There is an exception in case of masked blocks -- if the purpose of a callback function is to transfer mask parameter value from mask to all parameters with same name inside of the masked subsystem, then this is supported by QGen. Real-valued Computations Only ----------------------------- * QGen supports only integer and floating point -valued signals and computations. Complex values are not supported. * Fixed-point values are not supported, with an exception when automatically generated by Simulink for the blocks listed below. In such cases, fixed-point data type will be exported to XMI, and later on converted to integer (preserving sign and scaling) in QGen preprocessor. * The supported list of blocks is: * :ref:`cst-extract-bits` * The supported fixed-point formats are types: * starting with the "sfix" or the "ufix" prefix * if scaling is used, containing "E" or/and "n" characters in the encoding suffix * Refer to `Mathworks documentation`_ for more information about fixed-point formatting. .. _`Mathworks documentation`: https://www.mathworks.com/help/fixedpoint/ug/fixed-point-numbers.html * Parameters that control the signal type, e.g. "Output signal type" must have value "real" or "auto". Bus Signals ----------- * QGen supports both virtual and non-virtual buses. * Buses are supported at the input-output of following Simulink blocks * Bus Creator * Bus Selector * Bus Assignment * Signal Conversion * Inport * Outport * Unit Delay * Switch Forwarding Tables in Libraries ------------------------------ Forwarding Tables can be used in Simulink libraries. There are a few restrictions in their use: * Transformation Functions are not supported * The redirection of blocks can only be defined in the library where this block is defined. For example, if we want to map "LibA/BlockA" to "LibB/BlockB", this redirection can only be defined in "LibA". MISRA Simulink Guidelines ------------------------- QGen automatically checks that the input model conforms to selected MISRA Simulink constraints. QGenc should not be used as a MISRA checker tool. The checks are limited to constructs which directly influence the code generation policy. For full check one should use a dedicated MISRA checker. Via the --no-misra option, ``qgenc`` can cope with models violating the checked MISRA constraints. However, we suggest to adopt at minimum the following rules: * Blocks that can be configured to use saturation must have this flag off. The Saturation or Saturation Dynamic blocks should be used, if saturation is needed. * Blocks other than the Rounding block that can be configured to use different rounding options must be set to round towards zero. The only exception is Data Type Conversion, where the rounding option is also supported. * Data type conversion of block input and output should be done using the Data Type Conversion block and not by other blocks with block specific type conversion options. .. _simulink_parameters: Simulink Coder(TM) Parameters ------------------------------ ``qgenc`` respects selected parameters from Signal and Parameter object that do not influence the model semantics and are intended for tuning the Simulink Coder behaviour. The semantics may not be necessarily the same as that assumed by the Simulink coder. Below is the table of supported parameters their values and impact on the generated code. .. list-table:: Supported storage classes :header-rows: 1 :stub-columns: 1 * - Value - Notes - Ada - C * - Auto, Default, Global or SimulinkGlobal - In case of a Signal object, the variable is defined in module corresponding to containing subsystem. A constant corresponding to a Parameter object is defined in _params module. - `` : [constant] := ;`` - ``[const] = ;`` * - ExportedGlobal - A constant (in case of Parameter) or variable (in case of Signal) is defined in _params module. - `` : [constant] := ;`` - ``[const] = ;`` * - ExportToFile - The Header file parameter is obligatory. A constant (in case of Parameter) or variable (in case of Signal) is defined in the module defined in Header file parameter. - `` : [constant] := ;`` - ``[const] = ;`` * - ImportedExtern - A constant (in case of Parameter) or variable (in case of Signal) is defined with "extern" qualifier. If Header file parameter has value, with/include statement is generated for this module - `` : [constant] := ; pragma Import (Ada, , "");`` - ``extern [const] = ;`` * - ImportFromFile - The Header file parameter is obligatory. With/include statement is generated for this module. When generating ada code and the included module has ".h" extension, an additional import declaration is generates in module _params - `` : [constant] ; pragma Import (C, , "");`` - ``#include "
"`` * - Const - Applies to Parameter object only. Adds "const" qualifier to generated variable. Has effect only in case of --const-as-vars, as by default all parameters are treated as constants. - `` : constant := ;`` - ``const = ;`` * - Volatile - Adds "volatile" qualifier to generated variable/constant and import statement - `` : [constant] := ; pragma Import (Ada, , ""); pragma Volatile ();`` - ``volatile [const] = ;`` * - ConstVolatile - Applies to Parameter object only. Adds "const" qualifier to generated variable. Has effect only in case of --const-as-vars, as by default all parameters are treated as constants. - `` : constant := ; pragma Import (Ada, , ""); pragma Volatile ();`` - ``volatile const = ;`` * - Define - Applies to Parameter object only. Adds "const" qualifier to generated variable in case of Ada. In case of c generates a macro definition - `` : constant := ;`` - ``#define = ;`` The Header file parameter is supported for some storage classes as described above. The parameter or signal variable is defined in the module specified by the headerfile attribute. Depending on the storage class the module is either generated (ExportToFile) or assumed to exist (ImportFromFile, Volatile, Const, ConstVolatile). MATLAB ====== MATLAB .p and .mat Files --------------------------- MATLAB .p and .mat files are not supported. .. _eml-params-accepted-constructs: MATLAB Code for Parameters in .m Files and Block Parameters ----------------------------------------------------------- Dimensions of data ~~~~~~~~~~~~~~~~~~~~ Scalars, vectors and two-dimensional data (matrices) are supported. Data with more dimensions is not supported. Accepted Constructs ~~~~~~~~~~~~~~~~~~~ Only constant definitions are accepted in .m files. The supported format is: .. code-block:: text = [ (] [)]; where := [.] := | Datastructures are defined implicitly by assigning values for each structure element. There is currently no way to attach explicitly defined data type to a constant. Values can be composed of literal values, references to other constants and expressions including of arithmetic operators and supported functions (see section "MATLAB functions" below). Annotation delimiter is "%". Examples .. code-block:: text % Constant definition, implicit data type MyIntParam = 15; % Constant definition, explicit data type MyDoubleParam = double (100); % Array with explicit data type MyArrParam = double ([1 2 3]); % Definition of a constant structure MyStructParam.Elem1 = 1; MyStructParam.Elem2 = [1 2 3]; MyStructParam.Elem3 = MyIntParam; % Expression using other constants MyIntParam2 = int8 (MyIntParam + MyDoubleParam); Type Definitions ~~~~~~~~~~~~~~~~ * Type definitions are not supported in parameter .m-files. However, QGen supports several ways of using custom data types. See :ref:`custom-data-types` for further details. * The only exception is an implicit type definition of a structure (record) parameter. QGen infers the type definition from the instance definition in the parameter file. See :ref:`eml-params-accepted-constructs`. MATLAB Operators ---------------- The following unary operators are supported: .. code-block:: text + - ~ The following binary operators are supported: .. code-block:: text + - * .* / ^ < <= > >= ~= | || & && MATLAB Functions ---------------- The following MATLAB functions are supported in both .m files and Simulink block parameters: .. code-block:: text abs, acos, asin, atan, atan2, bin2dec, cos, cosh, exp, hex2dec, log, log10, min, max, mod, rem, round, sign, sin, sinh, sqrt, tan, tanh, transpose. Explicit typing/casting expressions are supported for: .. code-block:: text int8, int16, int32, uint8, uint16, uint32, single, double, logical In addition to numeric literals, the following literals are supported as well: .. code-block:: text INF, NaN MATLAB Expressions ------------------ Expressions containing the colon operator can only be used to get a slice of a vector (without increment value): .. code-block:: text mySlice = myVector(3:8); The following expressions are **not** supported: * Matrix partial indexing: .. code-block:: text myMatrix(:,1); myMatrix(1:3); * Creation of row vector: .. code-block:: text MyVector = [10:20]; * Vector slice with increment value: .. code-block:: text mySlice = myVector(1:5:20); In case there is a need for using such subarrays, then you should do the slicing in MATLAB and feed an appropriate subrarray to ``qgenc``. For instance when myMatrix is a two dimensional array and a model contains block parameter with value myMatrix (:,1) (i.e. the parameter is a vector containing the first column from matrix) then: * the original matrix is .. code-block:: text myMatrix = [1 2; 3 4]; * create a vector variable myVector1 in MATLAB .. code-block:: text myVector1 = myMatrix(:,1); * copy the vector value to the .m file that is given as an argument to ``qgenc`` .. code-block:: text myVector1 = [1 3]; * replace the expression "myMatrix(:,1)" in model with "myVector1" * assign to a structure in array: .. code-block:: text myVector1(1,2).member = 1; MATLAB cell arrays ------------------ Cell arrays in MATLAB workspace are not supported. qgen_export_workspace generates warning and array is not exported. When the array is referenced from Simulink model then code generation fails. .. _stateflow-rules: Stateflow chart modelling rules =============================== Stateflow charts must comply to the following modeling rules and constraints. Event broadcast for local events shall not to be used ----------------------------------------------------- **Description:** Stateflow event broadcast mechanism for Stateflow local events shall not to be used. Dataflow shall be used for controlling the chart's mode instead. **Note:** An exception is broadcasting external events, i.e. events that are received by other parts of the (Simulink) model than the broadcasting chart itself. Such events do not directly affect the behaviour of the chart. The only affect is changing global data. This kind of broadcasting is allowed. Typically the trigger type of the event/port is in such cases "function call". **Justification:** Some forms of event broadcast can lead to non-termination. Broadcasting an event in a transition action is one case that can never lead to non-termination by itself. In other cases static checks could be used to detect potentially looping behaviour. Input and output events of the chart shall have a "function call" trigger type ------------------------------------------------------------------------------ **Description:** The trigger type property of input and output events of a chart shall have a "function call" trigger type. **Justification:** This ensures the kind of timing of execution that is required by modelling/coding practices by some of the end-users. Output events with edge trigger type can create confusing models, because an event can be triggered several times in Stateflow, but is seen once or not at all in the Simulink part [REMOVED] --------- This constraint was applicable up to version 2.1.2 of QGen. It was removed in version 17 and is no longer relevant in subsequent versions. This section is preserved for traceability of constraints across different versions of QGen. [REMOVED] --------- This constraint was applicable up to version 1.0.1 of QGen. It was removed in version 2.0.1 and is no longer relevant in subsequent versions. This section is preserved for traceability of constraints across different versions of QGen. Transition actions shall not be used in graphical functions and pure flow-graph decompositions. Condition actions shall be used instead. ---------------------------------------------------------------------------------------------------------------------------------------- **Description:** Transition actions shall not be used in graphical functions and pure flow-graph decompositions. .. NOTE:: This rule applies to pure flow-graphs only. It **does not** concern OR compositions of states, where transition actions are very appropriate. **Justification:** This is a robustness constraint against effectively dead modelling constructs. Transition actions are meaningless in the above-mentioned cases since they are executed only when there is a transition from state to state (some versions of Stateflow allow to specify such actions, but they are never executed). In flow-graph networks condition actions should be used instead. An OR decomposition must always have an unguarded default transition -------------------------------------------------------------------- **Description:** An OR decomposition must always have an unguarded default transition. Exception: An OR decomposition with only one substate can exist without a default transition. However, when any default transitions are present, then at least one must be unguarded. **Justification:** If this condition is not satisfied then a run-time error due to state inconsistency can result, when a decomposition is entered, since it means that a system is in inconsistent state. When the decomposition consists of one substate only, then there is no need for the default transition. However, default transitions might exist, with different transitions specifying different actions. In the last case one of them must be without a guard to avoid confusion reading the model, as in Stateflow the state is nevertheless entered. [REMOVED] --------- This constraint was applicable up to version 17.1 of QGen. It was removed in version 17.2 and is no longer relevant in subsequent versions. This section is preserved for traceability of constraints across different versions of QGen. Boxes shall only be used for grouping functions ----------------------------------------------- **Description:** Boxes shall only be used for grouping functions. **Justification:** Justification: Using boxes around states or flow-graph networks creates strange and complex scoping. The logical scoping for executing the chart's sections and the name scopes introduced by boxes do not match. Boxes are fine for grouping graphical functions and truthtable functions. Only bounded flow-graph loops should be used -------------------------------------------- **Description:** Flow-graph loops can cause non-termination of the chart's execution. The loops should be designed with care and preferrably use a simple for-style pattern. .. NOTE:: This rule is currently not checked by QGen. The transition arc shall not leave its logical parent's boundary ---------------------------------------------------------------- **Description:** The transition arc shall not leave the boundary of the logical parent of the transition (the lowest common ancestor of the source and destination states). .. WARNING:: Stateflow issues a warning about such transition arcs when simulating the model. This rule is **not** checked by QGen. In case such arcs exist the behaviour in Stateflow can have some side-effects that are not taken into account by QGen. **Justification:** This is an error-prone pattern. The detailed semantics for such transitions is complicated and unintuitive. Identical or similar behaviour can be obtained by more clear and explicit constructs. Super step semantics shall not be used -------------------------------------- **Description:** The Stateflow super step semantics is not supported. This option should be turned off in charts supplied to QGen. Variable-size arrays shall not be used -------------------------------------- **Description:** The variable-size arrays in Stateflow are not supported. This option should be turned off in charts supplied to QGen. Only C action language shall be used ------------------------------------ **Description:** QGen does not support the MATLAB action language. Moore charts shall not be used for breaking data loops ------------------------------------------------------ **Description:** It is possible in Simulink/Stateflow to use Moore charts for breaking causality of data feedback loops (algebraic loops). This is currently not supported in QGen. If a Moore chart is used in a data feedback path make sure there is also some non-direct feedthrough block, such as Unit Delay on the same path. Simulink functions shall not be used ------------------------------------ **Description:** Using Simulink functions in Stateflow charts is currently not supported by QGen. Similar functionality can be modelled with an external Simulink subsystem that has the necessary data inputs-outputs connected to the chart's io and that is triggered by a function call event from the chart. History junctions shall not be used ----------------------------------- **Description:** History junctions are not supported by QGen. Their use is also deprecated by the MISRA AC SLSF guide (rule 046) as it complicates interpretation of the model's semantics. The history can be modelled with an explicit local variable and transitions instead. [CHANGED] Absolute-time temporal logic shall not be used -------------------------------------------------------- **Description:** The Stateflow absolute-time temporal logic operators and events are currently not supported by QGen. This constraint has been changed in QGen version 18, where the support for event-based temporal logic was added. In earlier versions neither event-based nor absolute-time temporal logic were supported. Change detection functions shall not be used -------------------------------------------- **Description:** The Stateflow change detection functions: 'hasChanged', 'hasChangedFrom' and 'hasChangedTo' are currently not supported by QGen. 'in ' operator shall not be used --------------------------------------- **Description:** The 'in ' operator is currently not supported by QGen. Data stores shall only be accessed through chart's I/O ------------------------------------------------------ **Description:** Defining or accessing data stores directly from Stateflow chart is not supported. If referring or modifying a value of a Data Store is needed in Stateflow, create resp. Data Store Read and Write blocks and connect them to the chart's I/O. Some C math functions are not supported ------------------------------------------------ **Description:** Most C math functions are supported. The exceptions are "labs", "atan2", "fmod", "ldexp" and "rand". Messages and queued communication are not supported --------------------------------------------------- **Description:** The Stateflow message objects and queued communication are not supported. If queuing is required, then the necessary mechanism should be explicitly modeled. An AND decomposition must not contain transitions or junctions -------------------------------------------------------------- **Description:** Transitions and junctions have proper semantics only for OR decompositions. In some cases Stateflow allows them also in AND decompositions, but this pattern shouldn't be used. Nested graphical functions are not supported -------------------------------------------- **Description:** QGen does not support nested graphical functions. Boxes are not supported in functions ------------------------------------ **Description:** QGen does not support boxes in graphical functions. Machine-level data are not supported ------------------------------------ **Description:** QGen does not support defining shared data at the Stateflow root level. Data objects must be defined at the level of a chart or below. Box-level data are not supported -------------------------------- **Description:** QGen only supports defining functions in boxes. Local or parameter data may be defined at a function level. .. WARNING:: This rule is currently not checked by QGen. The behaviour of simulation and code generated by QGen can be different. Simulink states are not supported --------------------------------- **Description:** QGen does not support the state kind 'Simulink state'. Custom C code is not supported ------------------------------ **Description:** QGen ignores any custom code specified in the model and such code cannot be referenced from Stateflow charts. Literal code (the literal code symbol '$') is not supported ----------------------------------------------------------- **Description:** Literal code (the literal code symbol $) is currently not supported in Stateflow actions and guards. The 'change' ('chg') event is not supported ------------------------------------------- **Description:** The implicit 'change' ('chg') event is currently not supported. The time symbol 't' is not supported ------------------------------------ **Description:** The absolute time symbol 't' is not supported by QGen. The reference '*' and dereference '&' operators are not supported ----------------------------------------------------------------- **Description:** These operators (i.e. pointers) are not supported in Stateflow guards and actions. The shorthand notation for combining multiple state action conditions is not supported -------------------------------------------------------------------------------------- **Description:** QGen doesn't support the state label notation where multiple action conditions have been combined. E.g., the following are not supported: .. code-block:: text en, ex: Out1++ du, on e1: Out2++ Workaround: Specify each action condition separately and duplicate the action. .. code-block:: text en: Out1++ ex: Out1++ du: Out2++ on e1: Out2++ Explicit type cast operator 'cast' is not supported --------------------------------------------------- **Description:** QGen doesn't currently support this operator. The type reference operator 'type' is not supported --------------------------------------------------- **Description:** QGen doesn't currently support this operator. The 'bind' keyword is ignored ----------------------------- **Description:** QGen currently ignores this keyword. The only place where this can cause a difference in the behavior between the simulation and the generated code is when a function-call event is bound to a state of a Stateflow chart. In this case the called subsystem will behave as if it was an enabled subsystem. This behaviour is not supported and the generated code is equivalent to a chart without the bind. .. WARNING:: This rule is currently not checked by QGen. The behaviour of simulation and code generated by QGen can be different. The 'Saturate on integer overflow' property of a Stateflow chart must be set to "off" -------------------------------------------------------------------------------------- **Description:** QGen does not support this feature. The 'Create output for monitoring' property of a Stateflow chart or state must be set to "off" ---------------------------------------------------------------------------------------------- **Description:** QGen does not support this feature. Stateflow functions with multiple output data definitions are not supported --------------------------------------------------------------------------- **Description:** QGen does not support multiple output data definitions (formal parameters with direction 'out') in Stateflow functions. However, a single non-scalar output is supported. The number of non-scalar input arguments is not limited. Stateflow functions with non-scalar output must only be used in simple assignments ---------------------------------------------------------------------------------- **Description:** QGen supports calling Stateflow functions with non-scalar output only from statements of following form: .. code-block:: text Y = fun(X) Combining and/or nesting such calls with other expressions is currently not supported. Inlining graphical functions is not supported --------------------------------------------- **Description:** QGen currently ignores the 'Function Inline Option' of Stateflow functions and treats them always as if the option was set to "Function". The first index of non-scalar data must be 0 (default) ------------------------------------------------------ **Description:** The 'First index' property of any Stateflow data object must be set to 0 or be unset (left to default). .. WARNING:: This rule is currently not checked by QGen. The behaviour of simulation and code generated by QGen can be different. Atomic subcharts are not supported ---------------------------------- **Description:** QGen doesn't currently support the option 'Atomic Subchart' in the 'Group & Subchart' properties of state objects. You may, however, use the options 'Group' and 'Subchart'. .. note:: This also means that subcharts cannot be referenced from libraries. To reuse charts place the entire chart to a library. Strong data typing with Simulink I/O must be used ------------------------------------------------- **Description:** The chart option "Use Strong Data Typing with Simulink I/O" must be set. Commented out elements are not supported ---------------------------------------- **Description:** QGen doesn't support commented out state chart elements, such as states, transitions, functions and junctions. Object names must not coincide with keywords -------------------------------------------- **Description:** The names of user-defined objects must not coincide with any Stateflow keyword. The list of currently known unsupported names is provided in the following section. In some cases using such a name for a user-defined object is supported in Stateflow, but such models have confusing and error-prone semantics. .. WARNING:: This rule is currently not checked by QGen. The behaviour of simulation and code generated by QGen can be different. Stateflow Keywords ~~~~~~~~~~~~~~~~~~ Boolean symbols * true * false Change detection * hasChanged * hasChangedFrom * hasChangedTo Complex data * complex * imag * real Data types * boolean * double * int8 * int16 * int32 * single * uint8 * uint16 * uint32 Data type operations * cast * fixdt * type Explicit events * send Implicit events * change * chg * tick * wakeup Messages * send * forward * discard * isvalid * length * receive Literal symbols * inf * t (C charts only) MATLAB functions and data * matlab * ml State actions * bind * du * during * en * entry * ex * exit * on State activity * in Temporal logic * after * at * before * every * sec * msec * usec * temporalCount * elapsed * t * duration * count C Math Functions * 'abs', 'fabs', 'sin', 'cos', 'tan', 'sinh', 'cosh', 'tanh', * 'asin', 'acos', 'atan', 'log', 'log10', 'ceil', 'floor', 'sqrt', * 'exp', 'pow', 'fmod', 'labs', 'ldexp', 'atan2', 'rand' Transition paths involving states must not contain flow-graph loops ------------------------------------------------------------------- **Description:** Transition paths that start or end in a state must not contain a flow-graph loop, i.e. a loop involving only transitions and junctions, on the transition path. .. note:: Transition paths that start and end in the same state, but do not involve a flow-graph loop according to the above criteria are not concerned by the current constraint and are allowed. Flow-graph loops involving only transitions and junctions are, however, allowed in graphical functions and inner compositions of states. Such graphical functions can, for example, also be called from transition or condition actions of transitions having a path to or from a state. Target Languages ================ Ada / SPARK ----------- QGen generates Ada code compliant with the Ada 83, Ada 95, Ada 2005, Ada 2012 and SPARK 2014 standards. Generated code might be non-compilable when the source of a Merge block is an atomic subsystem. This limitation will be fixed in a future QGen release. MISRA-C ------- QGen generates C code compliant with the C89 ANSI standard and MISRA C:2012 guidelines. XMI Support =========== The XMI importer has the following limitations: * The ``xsi:type`` of an object is specified using the fully qualified name: .. code-block:: text * The ``xmi:id`` attribute is used to resolve references to elements and is always required for every node. XPath expressions are not (and will not be) supported. For example, the following XMI is acceptable: .. code-block:: text ... Where the ``variable`` attribute in the first node references the ``xmi:id`` of the second node. * If two features are one the eOpposite of the other, the values for both need to be included in the XMI file. These limitations are not planned to be alleviated.