Calling C Functions in Actions

On this page…
Calling C Library Functions Calling the abs Function Calling min and max Functions Replacement of C Math Library Functions with Target-Specific Implementations Calling Custom C Code Functions

Calling C Library Functions

You can call this subset of the C Math Library functions:

abs* **	acos**	asin**	atan**	atan2**	ceil**
cos**	cosh**	exp**	fabs	floor**	fmod**
labs	ldexp**	log**	log10**	pow**	rand
sin**	sinh**	sqrt**	tan**	tanh**

^* The Stateflow abs function goes beyond that of its standard C counterpart with its own built-in functionality. See Calling the abs Function.

^** You can also replace calls to the C Math Library with target-specific implementations for this subset of functions. For more information, see Replacement of C Math Library Functions with Target-Specific Implementations.

When you can call these math functions, double precision applies unless the first input argument is explicitly single precision. When a type mismatch occurs, a cast of the input argument to the expected type replaces the original argument. For example, if you call the sin function with an integer argument, a cast of the input argument to a floating-point number of type double replaces the original argument.

If you call other C library functions not listed above, include the appropriate #include... statement in the Simulation Target > Custom Code pane of the Configuration Parameters dialog box. For details, see Building Targets.

Back to Top

Calling the abs Function

Interpretation of the Stateflow abs function goes beyond the standard C version to include integer and floating-point arguments of all types as follows:

• If x is an integer of type int32, the standard C function abs applies to x, or abs(x).

• If x is an integer of type other than int32, the standard C abs function applies to a cast of x as an integer of type int32, or abs((int32)x).

• If x is a floating-point number of type double, the standard C function fabs applies to x, or fabs(x).

• If x is a floating-point number of type single, the standard C function fabs applies to a cast of x as a double, or fabs((double)x).

• If x is a fixed-point number, the standard C function fabs applies to a cast of the fixed-point number as a double, or fabs((double)V_x), where V_x is the real-world value of x.

If you want to use the abs function in the strict sense of standard C, cast its argument or return values to integer types. See Type Cast Operations.

Note   If you declare x in custom code, the standard C abs function applies in all cases. For instructions on inserting custom code into Stateflow charts, see Building Targets.

Back to Top

Calling min and max Functions

You can call min and max by emitting the following macros automatically at the top of generated code.

#define min(x1,x2) ((x1) > (x2) ? (x2):(x1))
#define max(x1,x2) ((x1) > (x2) ? (x1):(x2))

To allow compatibility with user graphical functions named min() or max(), generated code uses a mangled name of the following form: <prefix>_min. However, if you export min() or max() graphical functions to other charts in your model, the name of these functions can no longer be emitted with mangled names in generated code and conflict occurs. To avoid this conflict, rename the min() and max() graphical functions.

Back to Top

Replacement of C Math Library Functions with Target-Specific Implementations

You can use the target function library published by Embedded Coder code generation software to replace the default implementations of a subset of C library functions with target-specific implementations (see Supported Target Library Functions). When you specify a target function library, Stateflow software generates code that calls the target implementations instead of the associated C library functions. Furthermore, Stateflow software also uses target implementations in cases where the compiler generates calls to math functions, such as in fixed-point arithmetic utilities.

Use of Target Function Libraries

To learn how to create and register code replacement tables in a target function library, see Example: Mapping Math Functions to Target-Specific Implementations in the Embedded Coder documentation. To select and view target function libraries, see Selecting and Viewing Target Function Libraries in the Simulink Coder documentation.

Supported Target Library Functions

You can replace the following math functions with target-specific implementations:

Function	Data Type Support
abs Note   See also Replacement of Calls to abs.	Floating-point and integer
acos	Floating-point
asin	Floating-point
atan	Floating-point
atan2	Floating-point
ceil	Floating-point
cos	Floating-point
cosh	Floating-point
exp	Floating-point
floor	Floating-point
fmod	Floating-point
ldexp	Floating-point
log	Floating-point
log10	Floating-point
max	Floating-point and integer
min	Floating-point and integer
pow	Floating-point
sin	Floating-point
sinh	Floating-point
sqrt	Floating-point
tan	Floating-point
tanh	Floating-point

Replacement of Calls to abs

Replacement of calls to abs can occur as follows:

Type of Argument for abs	Result
Floating-point	Replacement with target function
Integer	Replacement with target function
Fixed-point with zero bias	Replacement with ANSI C function
Fixed-point with nonzero bias	Error

Back to Top

Calling Custom C Code Functions

You can install your own C code functions for use in the Stateflow action language for simulation and for C code generation.

• Specifying Custom C Functions for Simulation

• Specifying Custom C Functions for Code Generation

• Guidelines for Calling Custom C Functions in Stateflow Action Language

• Guidelines for Writing Custom C Functions That Access Input Vectors

• Example of Function Call in Transition Action

• Example of Function Call in State Action

• Passing Arguments by Reference

Specifying Custom C Functions for Simulation

To specify custom C functions for simulation:

1. Open the Configuration Parameters dialog box.

2. Select Simulation Target > Custom Code.

3. Specify your custom C files, as described in Integrating Custom C Code for Nonlibrary Charts for Simulation.

Specifying Custom C Functions for Code Generation

To specify custom C functions for code generation:

1. Open the Configuration Parameters dialog box.

2. Select Code Generation > Custom Code.

3. Specify your custom C files, as described in Integrating Custom C Code for Nonlibrary Charts for Code Generation.

Guidelines for Calling Custom C Functions in Stateflow Action Language

• Define a function by its name, any arguments in parentheses, and an optional semicolon.

• Pass string parameters to user-written functions using single quotation marks. For example, func('string').

• An action can nest function calls.

• An action can invoke functions that return a scalar value (of type double in the case of MATLAB functions and of any type in the case of C user-written functions).

Guidelines for Writing Custom C Functions That Access Input Vectors

• Use the sizeof function to determine the length of an input vector.

  For example, your custom function can include a for-loop that uses sizeof as follows:

  for(i=0; i < sizeof(input); i++) {
  ......
  }

• If your custom function uses the value of the input vector length multiple times, include an input to your function that specifies the input vector length.

  For example, you can use input_length as the second input to a sum function as follows:

  int sum(double *input, double input_length)
  

  Your sum function can include a for-loop that iterates over all elements of the input vector:

  for(i=0; i < input_length; i++) {
  ......
  }

Example of Function Call in Transition Action

Example formats of function calls using transition action notation appear in the following chart.

A function call to fcn1 occurs with arg1, arg2, and arg3 if the following are true:

• S1 is active.

• Event e occurs.

• Condition c is true.

• The transition destination S2 is valid.

The transition action in the transition from S2 to S3 shows a function call nested within another function call.

Example of Function Call in State Action

Example formats of function calls using state action notation appear in the following chart.

Chart execution occurs as follows:

1. When the default transition into S1 occurs, S1 becomes active.

2. The entry action, a function call to fcn1 with the specified arguments, executes.

3. After 5 seconds of simulation time, S1 becomes inactive and S2 becomes active.

4. The during action, a function call to fcn2 with the specified arguments, executes.

5. After 10 seconds of simulation time, S2 becomes inactive and S1 becomes active again.

6. Steps 2 through 5 repeat until the simulation ends.

Passing Arguments by Reference

A Stateflow action can pass arguments to a user-written function by reference rather than by value. In particular, an action can pass a pointer to a value rather than the value itself. For example, an action could contain the following call:

f(&x);

where f is a custom-code C function that expects a pointer to x as an argument.

If x is the name of a data item defined in the Stateflow hierarchy, the following rules apply:

• Do not use pointers to pass data items input from a Simulink model.

  If you need to pass an input item by reference, for example, an array, assign the item to a local data item and pass the local item by reference.

• If x is a Simulink output data item having a data type other than double, the chart property Use strong data typing with Simulink I/O must be on (see Specifying Chart Properties).

• If the data type of x is boolean, you must turn off the coder option Use bitsets to store state-configuration (see How to Optimize Generated Code for Embeddable Targets).

• If x is an array with its first index property set to 0 (see Setting Data Properties in the Data Dialog Box), then the function must be called as follows.

  f(&(x[0]));

  This passes a pointer to the first element of x to the function.

• If x is an array with its first index property set to a nonzero number (for example, 1), the function must be called in the following way:

  f(&(x[1]));

  This passes a pointer to the first element of x to the function.

Back to Top

Supported Symbols in Action Language

Calling Built-In MATLAB Functions and Accessing Workspace Data

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS