-
Write Level-2 MATLAB S-Functions
About Level-2 MATLAB S-Functions
The Level-2 MATLAB? S-function API
allows you to use the MATLAB language to create
custom
blocks
with
multiple
input
and
output
ports
and
capable
of
handling
any
type
of
signal
produced
by
a
Simulink?
model,
including
matrix
and
frame
signals
of
any
data
type.
The
Level-2
MATLAB S-function API corresponds closely to the
API for creating C MEX S-functions.
Much
of
the
documentation
for
creating
C
MEX
S-functions
applies
also
to
Level-2
MATLAB
avoid duplication,
this section focuses on providing information that
is specific to
writing Level-2 MATLAB
S-functions.
A
Level-2
MATLAB
S-function
is
MATLAB
function
that
defines
the
properties
and
behavior
of
an
instance
of a
Level-2
MATLAB
S-Function
block
that
references
the
MATLAB
function in a Simulink model. The
MA
TLAB function itself comprises a set
of callback methods
(see
Level-2
MATLAB
S-Function
Callback
Methods)
that
the
Simulink
engine
invokes
when
updating or simulating the model. The
callback methods perform the actual work of
initializing
and computing the outputs
of the block defined by the S-function.
To facilitate these tasks, the engine
passes a run-time object to the callback methods
as an
argument. The run-time object
effectively serves as a MATLAB proxy for the
S-Function block,
allowing the callback
methods to set and access the block properties
during simulation or model
updating.
About Run-Time Objects
When the Simulink engine invokes a
Level-2 MATLAB S-function callback method,it
passes
an
instance
of
the
unTimeBlock
class
to
the
method
as
an
argument.
This
instance,
known
as
the
run-time
object
for
the
S-Function
block,
serves
the
same
purpose
for
Level-2
MATLAB
S-function
callback
methods
as
the
SimStruct
structure
serves
for
C
MEX
S-function
callback
methods.
The
object
enables
the
method
to
provide
and
obtain
information
about various
elements of the block ports, parameters,states,
and work vectors. The method does
this
by
getting
or
setting
properties
or
invoking
methods
of
the
block
run-time
object.
See
the
documentation for the unTimeBlock class
for information on getting and setting
run-time object properties and invoking
run-time object methods.
Run-time
objects
do
not
support
MA
TLAB
sparse
matrices.
For
example,
if
the
variable
block is a run-time object, the
following line in a Level-2 MATLAB S-function
produces an error:
t(1).Data =
speye(10);
where the speye command
forms a sparse identity matrix.
Note
：
Other MATLAB
programs besides MATLAB S-functions can use run-
time objects to
obtain information
about a MATLAB S-function in a model that is
simulating. See Access Block
Data
During Simulation in Using Simulink for more
information.
Level-2 MATLAB S-Function
Template
Use the basic Level-2 MATLAB
S-function template msfuntmpl_tmpl_basic.m
to get a head start on creating a new
Level-2 MATLAB S-function. The template contains
skeleton
implementations
of
the
required
callback
methods
defined
by
the
Level-2
MATLAB
S-function
API.
To
write
a
more
complicated
S-function,
use
the
annotated
template
tmpl.m.
To create a MATLAB S-function, make a
copy of the template and edit the copy as
necessary
to
reflect
the
desired
behavior
of
the
S-function
you
are
creating.
The
following
two
sections
describe the
contents of the MATLAB code template. The section
Example of Writing a Level-2
MATLAB
S-Function describes how to write a Level-2 MATLAB
S-function that models a unit
delay.
Level-2 MATLAB S-Function Callback
Methods
The Level-2 MATLAB S-function
API defines the signatures and general
purposes of the callback methods that constitute a
Level-2
MATLAB
S-function.
The
S-function
itself
provides
the
implementations
of
these
callback
methods. The implementations in turn
determine the block attributes (e.g., ports,
parameters, and
states) and behavior
(e.g., the block outputs as a function of time and
the block inputs, states, and
parameters).
By
creating
an
S-function
with
an
appropriate
set
of
callback
methods,
you
can
define a block type that meets the
specific requirements of your application.
A Level-2 MATLAB S-function must
include the following callback methods:
A setup function to initializethe basic
S-function characteristics
An Outputs
function to cal
culatethe S-function
outputs
Your S-function can contain
other methods, depending on the requirements of
the block that
the S-function defines.
The methods defined by the Level-2 MATLAB
S-function API generally
correspond to
similarly named methods defined by the C MEX
S-function API. For information
on
when
these
methods
are
called
during
simulation,
see
Process
View
in
Simulink
Engine
Interaction with C S-Functions. For
instructions on how to implement each callback
method, see
Write Callback Methods.
The following table lists all the
Level-2 MATLAB S-function callback methods and
their C
MEX counterparts.
Level-2 MATLAB Method
Equivalent C MEX Method
setup (see Using the setup Method)
mdlInitializeSizes
CheckParameters
mdlCheckParameters
Derivatives
mdlDerivatives
Disable
mdlDisable
Enable
mdlEnable
InitializeConditions
mdlInitializeConditions
Outputs
mdlOutputs
PostPropagationSetup
mdlSetWorkWidths
ProcessParameters
mdlProcessParameters
Projection
mdlProjection
SetInputPortComplexSignal
mdlSetInputPortComplexSignal
SetInputPortDataType
mdlSetInputPortDataType
SetInputPortDimensions
mdlSetInputPortDimensionInfo
SetInputPortDimensionsModeFcn
mdlSetInputPortDimensionsModeFcn
SetInputPortSampleTime
mdlSetInputPortSampleTime
SetInputPortSamplingMode
mdlSetInputPortFrameData
SetOutputPortComplexSignal
mdlSetOutputPortComplexSignal
SetOutputPortDataType
mdlSetOutputPortDataType
SetOutputPortDimensions
mdlSetOutputPortDimensionInfo
SetOutputPortSampleTime
mdlSetOutputPortSampleTime
SimStatusChange
mdlSimStatusChange
Start
mdlStart
Terminate
mdlTerminate
Update
mdlUpdate
WriteRTW
mdlRTW
Using the setup Method
The
body
of
the
setup
method
in
a
Level-2
MATLAB
S-function
initializes
the
instance
of
the
corresponding Level-2
MATLAB S-Function block. In this respect, the
setup method is similar to
the
mdlInitializeSizes and mdlInitializeSampleTimes
callback methods implemented by C MEX
S-functions. The setup method performs
the following tasks:
Initializing
the number of input and output portsof the block.
Setting
attributes
such
as
dimensions,
data
types,complexity,
and
sample
times
for
these
ports.
Specifying
the
block
sample
time.
See
Specify
Sample
Time
in
Using
Simulink
for
more
information on how to specify valid
sample times.
Setting the number of
S-function dialog parameters.
Registering
S-function
callback
methods
by
passing
the
handles
of
local
functions
in
the
MATLAB S-function to the RegBlockMethod
method of the S-Function block's run-time object.
See
the
documentation
for
unTimeBlock
for
information
on
using
the
RegBlockMethod method.
Example of Writing a Level-2 MATLAB
S-Function
The
following
steps
illustrate
how
to
write
a
simple
Level-2
MATLAB
S-function.
When
applicable,the
steps
include
examples
from
the
S-function
example
msfcn_unit__unit_delay.m
used
in
the
model
msfcndemo_sfundsc2msfcndemo_sfundsc2.
All lines of code use the variable name block for
the
S-function run-time object.
the Level-2 MATLAB S-function template
msfuntmpl_tmpl_basic.m to
your
working
folder.
If
you
change
the
file
name
when
you
copy
the
file,
change
the
function
name
in the function line to the same name.
the setup method to initialize the S-function's
attributes. For this example:
Set
the
run-time
object's
NumInputPorts
and
NumOutputPorts
properties
to
1
in
order
to
initialize one input port and one
output port.
Invoke
the
run-time
object's
SetPreCompInpPortInfoToDynamic
and
SetPreCompOutPortInfoToDynamic
methods
to
indicate
that
the
input
and
output
ports
inherit
their compiled properties (dimensions,
data type, complexity, and sampling mode)from the
model.
Set
the
DirectFeedthrough
property
of
the
run-time
object's
InputPort
to
false
in
order
to
indicate
the
input
port
does
not
have
direct
feedthrough.
Retain
the
default
values
for
all
other
input and output port properties that
are set in your copy of the template file. The
values set for the
Dimensions,
DatatypeID,
and
Complexity
properties
override
the
values
inherited
using
the
SetPreCompInpPortInfoToDynamic and
SetPreCompOutPortInfoToDynamic methods.
Set the run-time object's NumDialogPrms
property to 1 in order to initialize one
S-function
dialog parameter.
Specify that the S-function has an
inherited sample time by setting the value of the
runtime
object's SampleTimes property
to [-1 0].
Call
the
run-time
object's
RegBlockMethod
method
to
register
the
following
four
callback