Specify Types of Entry-Point Function Inputs - MATLAB & Simulink (original) (raw)
Main Content
Because C and C++ are statically typed languages, the code generator must determine the class and size of all variables in the generated code during code generation. To generate C/C++ code with specific variable types, you must specify the types of all inputs to your entry-point function. Input-type specification is a critical step in the Code Generation Workflow.
If your entry-point functions do not have inputs, you can skip this step. You do not need to specify the class and size of inputs to non-entry-point functions.
Methods of Input-Type Specification
You must specify the class and size of all inputs to your entry-point functions. For aggregate types, such as classes, structures, and cell arrays, you must also specify the class and size of each property, field, and element, respectively. You can specify input types in the MATLAB® Coder™ app, at the command line by using the codegen command with the -args option, in your MATLAB entry-point function by using function argument validation (arguments blocks), or in your MATLAB code by using preconditioning (assert statements). This table outlines the advantages and disadvantages of each of these methods.
| Method | Advantages | Disadvantages |
|---|---|---|
| Define Types of Entry-Point Inputs by Using the MATLAB Coder App | Easy to use, even when specifying aggregate data types such as cells or structuresDoes not alter original MATLAB codeThe code generator saves the type definitions in the project file | Input types are not documented in the MATLAB code |
| Specify Input Types at the Command Line | Designed for prototyping functions with few inputsEasy to use for fixed-size, non-aggregate inputs or those that can be specified by exampleDoes not alter original MATLAB code | Inputs must be specified every time you generate code unless you use a scriptSyntax for variable-size or aggregate inputs can be complicated |
| Use Function Argument Validation to Specify Entry-Point Input Types | Allows you to specify the aspects of the arguments required for code generation in a dedicated code blockResults in clearer and more concise MATLAB code compared to input-type specification using assert statementsSimplifies code generation because you do not specify input types each time you generate code in the MATLAB Coder app or at the command lineDocuments argument specifications in the MATLAB entry-point function | Does not support certain input types, including cells and structures. For a workaround, see Resolve Issue: Using arguments Blocks to Specify Cell or Structure Entry-Point Input Types is Not Supported.Calls to the generated MEX or C/C++ functions must include all arguments defined in the arguments block.Does not support the -float2fixed option with the codegen command. |
| Specify Input Types Using assert Statements in MATLAB Code | Simplifies code generation because you do not specify input types each time you generate code in the MATLAB Coder app or at the command lineDocuments argument specifications in your MATLAB code. | Uses complex syntaxBecause assert statements can appear anywhere in the MATLAB code, can be difficult to diagnose issues related to input-type specification that arise during code generation or at run time |
Unused Inputs
If one or more of your entry-point functions has unused input variables, code generation has certain considerations that depend on the method of input-type specification you use.
- If you specify input types by using the
codegenfunction with the-argsoption, you do not have to specify the unused input variables. However, all used variables must appear before all unused variables in the function declaration. Unused and unspecified variables do not appear in the generated code. - If all of the inputs to your MATLAB entry-point functions are unused and you specify the input types by using the
codegenfunction with the-argsoption, you can generate a C/C++ function with no inputs by passing an empty cell array{}to-args. - If you use the MATLAB Coder app to specify input types, you must specify the types of the unused inputs. The unused inputs appear in the generated code.
- If you define the input types in your MATLAB code using
argumentsblocks orassertstatements, you must specify the types of the unused inputs. You cannot specify unused inputs by using the tilde character (~). The unused inputs appear in the generated code.
Tips
- To specify an input that is a fixed-point fi (Fixed-Point Designer) object, you must configure the associated numerictype (Fixed-Point Designer) and fimath (Fixed-Point Designer) objects.
- To generate a multisignature MEX function from an entry-point function, provide multiple
-argsspecifications for the same entry-point function. The generated MEX function works with the multiple signatures that you provide during code generation. For more information on multisignature MEX function generation, see Generate Code for Functions with Multiple Signatures. - If you generate a MEX, SIL, or PIL function that accepts an empty array with a given shape, the generated function accepts empty arrays of other shapes as well. The MEX, SIL, or PIL function reshapes the empty run-time input array to match the shape of the array that was specified during code generation. See Incompatibility with MATLAB Due to Resizing of Empty Arrays by MEX, SIL, and PIL Functions.