################################ QGen Constraints on Input Models ################################ Simulink Version ================ The QGen toolset is compatible with MATLAB and Simulink versions R2009b 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. * 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 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 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; .. _stateflow-rules: 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 chart modelling rules =============================== The following modeling rules for Stateflow Charts are enforced. 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. .. WARNING:: This rule is currently not checked by QGen. The behaviour of simulation and code generated by QGen can be different. 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. .. NOTE:: This rule is currently not checked by 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. Truth tables shall not be used ------------------------------ **Description:** Truth table functions are currently not supported by QGen. Similar functionality can be modelled with graphical functions. 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. 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.