coder.cstructname - Name C structure type in generated code - MATLAB (original) (raw)

Name C structure type in generated code

Syntax

Description

coder.cstructname names the generated or externally defined C structure type to use for MATLAB® variables that are represented as structures in generated code.

coder.cstructname([var](#d126e13735),[structName](#d126e13760)) names the C structure type generated for the MATLAB variable var. The inputvar can be a structure or a cell array. Use this syntax in a function from which you generate code. Placecoder.cstructname after the definition ofvar and before the first use ofvar. If var is an entry-point (top-level) function input argument, placecoder.cstructname at the beginning of the function, before any control flow statements.

example

coder.cstructname([var](#d126e13735),[structName](#d126e13760),'extern','HeaderFile',[headerfile](#d126e13779)) specifies that the C structure type to use for var has the name structName and is defined in the external file,headerfileName.

It is possible to use the 'extern' option without specifying the header file. However, it is a best practice to specify the header file so that the code generator produces the #include statement in the correct location.

example

coder.cstructname([var](#d126e13735),[structName](#d126e13760),'extern','HeaderFile',[headerfile](#d126e13779),'Alignment',[alignment](#d126e13849)) also specifies the run-time memory alignment for the externally defined structure type structName. If you have Embedded Coder® and use custom Code Replacement Libraries (CRLs), specify the alignment so that the code generator can match CRL functions that require alignment for structures. See Data Alignment for Code Replacement (Embedded Coder).

`outtype` = coder.cstructname([intype](#d126e13873),[structName](#d126e13760)) returns a structure or cell array type object outtype that specifies the name of the C structure type to generate.coder.cstructname creates outtype with the properties of the input type intype. Then, it sets the TypeName property to structName. Use this syntax to create a type object that you use with thecodegen -args option. You cannot use this syntax in a function from which you generate code.

You cannot use this syntax in a MATLAB Function block.

example

`outtype` = coder.cstructname([intype](#d126e13873),[structName](#d126e13760),'extern','HeaderFile',[headerfile](#d126e13779)) returns a type object outtype that specifies the name and location of an externally defined C structure type. The code generator uses the externally defined structure type for variables with typeouttype.

You cannot use this syntax in a MATLAB Function block.

`outtype` = coder.cstructname([intype](#d126e13873),[structName](#d126e13760),'extern','HeaderFile',[headerfile](#d126e13779),'Alignment',[alignment](#d126e13849)) creates a type object outtype that also specifies the C structure type alignment.

You cannot use this syntax in a MATLAB Function block.

Examples

collapse all

Name the C Structure Type for a Variable in a Function

In a MATLAB function, myfun, assign the nameMyStruct to the generated C structure type for the variablev.

function y = myfun() %#codegen v = struct('a',1,'b',2); coder.cstructname(v, 'myStruct'); y = v; end

Generate standalone C code. For example, generate a static library.

codegen -config:lib myfun -report

To see the generated structure type, opencodegen/lib/myfun/myfun_types.h or viewmyfun_types.h in the code generation report. The generated C structure type is:

typedef struct { double a; double b; } myStruct;

Name the C Structure Type Generated for a Substructure

In a MATLAB function, myfun1, assign the nameMyStruct to the generated C structure type for the structure v. Assign the namemysubStruct to the structure type generated for the substructurev.b.

function y = myfun() %#codegen v = struct('a',1,'b',struct('f',3)); coder.cstructname(v, 'myStruct'); coder.cstructname(v.b, 'mysubStruct'); y = v; end

The generated C structure type mysubStruct is:

typedef struct { double f; } mysubStruct;

The generated C structure type myStruct is:

typedef struct { double a; mysubStruct b; } myStruct;

Name the Structure Type Generated for a Cell Array

In a MATLAB function, myfun2, assign the namemyStruct to the generated C structure type for the cell arrayc.

function z = myfun2() c = {1 2 3}; coder.cstructname(c,'myStruct') z = c;

The generated C structure type for c is:

typedef struct { double f1; double f2; double f3; } myStruct;

Name an Externally Defined C Structure Type

Specify that a structure passed to a C function has a structure type defined in a C header file.

Create a C header file mycadd.h for the functionmycadd that takes a parameter of typemycstruct. Define the typemycstruct in the header file.

#ifndef MYCADD_H #define MYCADD_H

typedef struct { double f1; double f2; } mycstruct;

double mycadd(mycstruct *s); #endif

Write the C functionmycadd.c.

#include <stdio.h> #include <stdlib.h>

#include "mycadd.h"

double mycadd(mycstruct *s) { return s->f1 + s->f2; }

Write a MATLAB function mymAdd that passes a structure by reference to mycadd. Usecoder.cstructname to specify that in the generated code, the structure has the C type mycstruct, which is defined in mycadd.h.

function y = mymAdd %#codegen s = struct('f1', 1, 'f2', 2); coder.cstructname(s, 'mycstruct', 'extern', 'HeaderFile', 'mycadd.h'); y = 0; y = coder.ceval('mycadd', coder.ref(s));

Generate a C static library for functionmymAdd.

codegen -config:lib mymAdd mycadd.c

The generated header file mymadd_types.h does not contain a definition of the structure mycstruct becausemycstruct is an external type.

Create a Structure Type Object That Names the Generated C Structure Type

Suppose that the entry-point function myFunction takes a structure argument. To specify the type of the input argument at the command line:

1. Define an example structure S.
2. Create a type T from S by using coder.typeof.
3. Use coder.cstructname to create a typeT1 that:
   • Has the properties of T.
   • Names the generated C structure typemyStruct.
4. Pass the type to codegen by using the-args option.

For example:

S = struct('a',double(0),'b',single(0)); T = coder.typeof(S); T1 = coder.cstructname(T,'myStruct'); codegen -config:lib myFunction -args T1

Alternatively, you can create the structure type directly from the example structure.

S = struct('a',double(0),'b',single(0)); T1 = coder.cstructname(S,'myStruct'); codegen -config:lib myFunction -args T1

Input Arguments

collapse all

var — MATLAB structure or cell array variable

structure | cell array

MATLAB structure or cell array variable that is represented as a structure in the generated code.

structName — Name of C structure type

character vector | string scalar

Name of generated or externally defined C structure type, specified as a character vector or string scalar.

headerfile — Header file that contains the C structure type definition

character vector | string scalar

Header file that contains the C structure type definition, specified as a character vector or string scalar.

To specify the path to the file:

• Use the codegen -I option or the Additional include directories parameter on the MATLAB Coder™ app settings Custom Code tab.
• For a MATLAB Function block, on theSimulation Target and the > panes, under Additional build information, set the Include directories parameter.

Alternatively, use coder.updateBuildInfo with the'addIncludePaths' option.

Example: 'mystruct.h'

alignment — Run-time memory alignment for structure

-1 (default) | power of 2

Run-time memory alignment for generated or externally defined structure.

intype — Type object or variable for creation of new type object

coder.StructType | coder.CellType | structure | cell array

Structure type object, cell array type object, structure variable, or cell array variable from which to create a type object.

Limitations

• You cannot apply coder.cstructname directly to a global variable. To name the structure type to use with a global variable, usecoder.cstructname to create a type object that names the structure type. Then, when you run codegen, specify that the global variable has that type. See Name the C Structure Type to Use with a Global Structure Variable.
• For cell array inputs, the field names of externally defined structures must be f1, f2, and so on.
• You cannot apply coder.cstructname directly to a class property.

Tips

• For information about how the code generator determines the C/C++ types of structure fields, see Mapping MATLAB Types to Types in Generated Code.
• Using coder.cstructname on a structure array sets the name of the structure type of the base element, not the name of the array. Therefore, you cannot apply coder.cstructname to a structure array element, and then apply it to the array with a different C structure type name. For example, the following code is not allowed. The secondcoder.cstructname attempts to set the name of the base type to myStructArrayName, which conflicts with the previously specified name,myStructName.
  % Define scalar structure with field a
  myStruct = struct('a', 0);
  coder.cstructname(myStruct,'myStructName');
  % Define array of structure with field a
  myStructArray = repmat(myStruct,4,6);
  coder.cstructname(myStructArray,'myStructArrayName');
• Applying coder.cstructname to an element of a structure array produces the same result as applyingcoder.cstructname to the entire structure array. If you apply coder.cstructname to an element of a structure array, you must refer to the element by using a single subscript. For example, you can use var(1), but not var(1,1). Applyingcoder.cstructname to var(:) produces the same result as applying coder.cstructname tovar or var(n).
• Heterogeneous cell arrays are represented as structures in the generated code. Here are considerations for using coder.cstructname with cell arrays:
  • In a function from which you generate code, usingcoder.cstructname with a cell array variable makes the cell array heterogeneous. Therefore, if a cell array is an entry-point function input and its type is permanently homogeneous, then you cannot usecoder.cstructname with the cell array.
  • Using coder.cstructname with a homogeneouscoder.CellType objectintype makes the returned object heterogeneous. Therefore, you cannot usecoder.cstructname with a permanently homogeneous coder.CellType object. For information about when a cell array is permanently homogeneous, see Specify Cell Array Inputs at the Command Line.
  • When used with a coder.CellType object, coder.cstructname creates a coder.CellType object that is permanently heterogeneous.
• When you use a structure named by coder.cstructname in a project with row-major and column-major array layouts, the code generator renames the structure in certain cases, appending row_ orcol_ to the beginning of the structure name. This renaming provides unique type definitions for the types that are used in both array layouts.
• These tips apply only to MATLAB Function blocks:
  • MATLAB Function block input and output structures are associated with bus signals. The generated name for the structure type comes from the bus signal name. Do not usecoder.cstructname to name the structure type for input or output signals. See Create Structures in MATLAB Function Blocks (Simulink).
  • The code generator produces structure type names according to identifier naming rules, even if you name the structure type withcoder.cstructname. If you have Embedded Coder, you can customize the naming rules. See Construction of Generated Identifiers (Embedded Coder).

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Version History

Introduced in R2011a