MATLAB Data in C S-Functions
MATLAB® data is represented as mxArrays
in C/C++ language. The
mxArray
structure typically contains type, dimension, data, data
type, sparsity, and the field and field numbers of the MATLAB array. In S-functions, Pass Dialog Parameters to S-Functions values evaluated in MATLAB are transferred into Simulink® as an mxArray
. See C Matrix API
for a list of functions.
S-functions read MATLAB data mainly for the following purposes:
Access block dialog parameters using
mxArrays
Pass arguments to or from a MATLAB Function using
mexCallMATLAB
mxArray
Manipulation
You can manipulate mxArrays
in S-functions using the standard
MATLAB API functions. In general, if your S-function is declared exception
free by passing the SS_OPTION_EXCEPTION_FREE_CODE
option to
ssSetOptions
(see Exception Free Code in Handle Errors in S-Functions), it should avoid MATLAB API functions that throw exceptions (i.e., long jump), such as
mxCreateDoubleMatrix
. Otherwise, the S-function can use any
of the listed functions.
Note
S-function parameters are read-only within the S-function algorithm. You can modify parameter values via the S-function block dialog or mask.
If you have Simulink
Coder™, it supports a subset of the mxArray
manipulation
functions when generating noninlined code for an S-function. For a list of supported
functions, see Write Noninlined S-Function (Simulink Coder).
Calls to the macro ssGetSFcnParam
return a pointer to an
mxArray
, which can be used with the
mxArray
manipulation functions. If your S-function contains
S-function parameters, use the mxArray
manipulation functions in
the mdlCheckParameters
method to check the S-function parameter
values. See the S-function sfun_runtime3.c
for an example
In this S-function, the following lines check that the first S-function parameter is a character array with a length greater than or equal to two.
if (!mxIsChar(ssGetSFcnParam(S, 0)) || (nu=mxGetNumberOfElements(ssGetSFcnParam(S, 0))) < 2) { ssSetErrorStatus(S,"1st parameter to S-function must be a " "string of at least 2 '+' and '-' characters"); return; }
mxArrays
Using 32-bit APIs
To write C/C++ programs that work with MATLAB
mxArray
data structure, use C matrix APIs. C matrix APIs support
32-bit and 64-bit indexing. By default, your S-functions are built using 32-bit
APIs. Check Upgrade MEX Files to Use 64-Bit API to see how to upgrade your existing MEX
files.
To check the use of 32-bit APIs, you can run the S-function upgrade advisor. In the Modeling tab, select Model Advisor > Upgrade Advisor.
If you build your code with -largeArrayDims
and your code
populates the ssParamRec
structure's dimension field with
mxArray
dimensions, starting R2018a, you can no longer cast
the return value of mxGetDimensions
to an int_T
pointer
because mxGetDimensions
now returns a
size_T
pointer on 64-bit platforms. As a workaround, create a
temporary copy of type int_T
and assign it to the
dims
field of ssParamRec
structure.
Replace: | With: |
---|---|
ssParamRec p; p.dims = (int_T *) mxGetDimensions(ssGetSFcnParam(S, 0)); // Set up other fields of p if (!ssSetRunTimeParamInfo(S, 0, &p)) { free(dims); return; } free(dims); // free memory allocated for dimensions |
ssParamRec p; const mxArray* mxPrm = ssGetSFcnParam(S, 0); const mwSize* mxDims = mxGetDimensions(mxPrm); const mwSize mxNumDims = mxGetNumberOfDimensions(mxPrm); mwSize idx; int_T * dims = malloc(sizeof(int)*mxNumDims); for (idx=0; idx < mxNumDims; idx++) { dims[idx] = mxDims[idx]; } p.dims = dims; // Set up other fields of p if (!ssSetRunTimeParamInfo(S, 0, &p)) { free(dims); return; } free(dims); // free memory allocated for dimensions |
mxArrays
Using Interleaved Complex Representation
Until MATLAB version 9.4 (R2018a), mxArrays
used separate
complex representation where the real and imaginary parts of a complex number were
stored separately. Starting version 9.4 (R2018a), MATLAB uses interleaved representation to store complex data, where the real
and imaginary parts of a complex numbers are stored together. For S-functions to
manipulate mxArrays
, there is no longer need to convert data from
separate to interleaved complex. See MATLAB Support for Interleaved Complex API in MEX Functions for more
information on how to update your code.
Note
To store complex data for input and output signals or DWorks, Simulink uses interleaved representation.
To automatically check your S-functions on potential interleaved complex data issues, in the Modeling tab, select Model Advisor > Upgrade Advisor. In the Upgrade Advisor window, select Check model for S-function upgrade issues.
The following code sample copies a parameter value from an
mxArray
to the output of the S-function. In this example, the
dimensions, data type, and the complexity of the parameter and the output argument
are ensured to be the same. For example, if the parameter is complex, the output
signal is complex. If the parameter is real, the output signal is real. For the
example below, the data type of both the parameter and the output is a double
(real_T
). Before R2018a, you could use
mxGetPr
and mxGetPr
to copy the real and
imaginary parts of a complex data separately. With interleaved complex
representation, you can use memcpy
, which is a single copy
instruction.
Replace: | With: |
---|---|
real_T *y = ssGetOutputPortRealSignal(S,0); boolean_T yIsComplex = ssGetOutputPortComplexSignal(S, 0) == COMPLEX_YES; int_T yWidth = ssGetOutputPortWidth(S,0); const real_T *pr = mxGetPr(ssGetSFcnParam(S, 0)); const real_T *pi = mxGetPi(ssGetSFcnParam(S, 0)); int i; for (i = 0; i < yWidth; i++) { int_T idx = (yIsComplex) ? 2*i : i; y[idx] = pr[idx]; if(yIsComplex){ y[idx+1] = pi[idx]; } } |
real_T *y = ssGetOutputPortRealSignal(S,0); boolean_T yIsComplex = ssGetOutputPortComplexSignal(S, 0) == COMPLEX_YES; int_T yWidth = ssGetOutputPortWidth(S,0); mxComplexDouble *pc; mxDouble *pr; if (yIsComplex) { pc = mxGetComplexDoubles(ssGetSFcnParam(S, 0)); memcpy(y, pc, yWidth*sizeof(mxComplexDouble)); } else { pr = mxGetDoubles(ssGetSFcnParam(S, 0)); memcpy(y, pr, yWidth*sizeof(mxDouble)); } |
a
|
See Also
S-Function | S-Function Builder