Returns 1 (true) if the specified block input port index has symbolic dimensions. This function take the port index as an input argument.
See LibBlockInputHasSymbolicWidth
in blkio_api.tlc
.
Determines the index mode of a block's input port.
block
— Block record
pidx
— Port index
""
for a nonindex port, and "Zero-based"
or
"One-based"
otherwise.
If an input port of a block
is set as an index port and its
indexing base is marked as zero-based or one-based, this information is written into the
file.
model
.rtwLibBlockInputPortIndexMode
queries the indexing base to branch to
different code according to what the input port indexing base is.
%if LibBlockInputPortIndexMode(block, pidx) == "Zero-based" ... %elseif LibBlockInputPortIndexMode(block, pidx) == "One-based" ... %else ... %endif
See LibBlockInputPortIndexMode
in
.blkiolib.tlc
Returns whether the input port accepts a co-simulation signal. This function takes the port index as an input argument.
See LibBlockInputPortIsContinuousQuantity
in blkio_api.tlc
.
Based on the input port number (portIdx
), the user control variable
(ucv
), the loop control variable (lcv
), the signal
index (sigIdx
), and where this input signal is coming from,
LibBlockInputSignal
returns the reference to a block input
signal.
The returned string value is a valid rvalue
(right-side value) for an
expression. The block input signal can come from another block, a state vector, or an
external input, or it can be a literal constant (e.g., 5.0).
Note
Do not use LibBlockInputSignal
to access the address of an input
signal.
Because the returned value can be a literal constant, you should not use
LibBlockInputSignal
to access the address of an input signal. To access
the address of an input signal, use LibBlockInputSignalAddr
. Accessing
the address of the signal via LibBlockInputSignal
can result in a
reference to a literal constant (e.g., 5.0).
For example, the following would not work.
%assign u = LibBlockInputSignal(0, "", lcv, sigIdx) x = &%<u>;
If %<u>
refers to an invariant signal with a value of
4.95
, the statement (after being processed by the preprocessor) would
be generated as
x = &4.95;
or, if the input signal sources to ground, the statement could come out as
x = &0.0;
Neither of these would compile.
Avoid such situations by using LibBlockInputSignalAddr
.
%assign uAddr = LibBlockInputSignalAddr(0, "", lcv, sigIdx) x = %<uAddr>;
The code generator tracks signals and parameters accessed by their addresses and declares them in addressable memory.
The following table summarizes the input arguments to
LibBlockInputSignal
.
LibBlockInputSignal Arguments
Argument | Description |
---|---|
| Integer specifying the input port index (zero-based). Note: For certain
built-in blocks, |
| User control variable. Must be a string, either an indexing expression
or |
| Loop control variable. Must be a string, either an indexing expression
or |
| Either an integer literal or a string of the form %<tRealPart>Integer %<tImagPart>Integer For example, the following signifies the real part of the signal and the imaginary part of the signal starting at 5: "%<tRealPart>5" "%<tImagPart>5" |
Uses of LibBlockInputSignal
fall into the categories described
below.
Direct indexing. If ucv == ""
and lcv == ""
,
LibBlockInputSignal
returns an indexing expression for the element
specified by sigIdx
.
Loop rolling/unrolling. In this case, lcv
and sigIdx
are generated by
the %roll
directive, and ucv
must be
""
. A nonempty value for lcv
is allowed only
when generated by the %roll
directive and when using the Roller TLC
file (or a user supplied Roller TLC file that conforms to the same variable/signal
offset handling). In addition, calls to LibBlockInputSignal
with
lcv
should occur only when "U"
or a specific
input port (e.g., "u0"
) is passed to the %roll
directive via the roll variables argument.
The following example shows a single input/single output port S-function.
%assign rollVars = ["U", "Y", "P"] %roll sigIdx=RollRegions, lcv=RollThreshold, block, ... "Roller", rollVars %assign u = LibBlockInputSignal( 0, "", lcv, sigIdx) %assign y = LibBlockOutputSignal(0, "", lcv, sigIdx) %assign p = LibBlockParameter( 0, "", lcv, sigIdx) %<y> = %<p> * %<u>; %endroll
With the %roll
directive, sigIdx
is the
starting index of the current roll region and lcv
is
""
or an indexing variable. The following are examples of valid
values:
LibBlockInputSignal(0, "", lcv, sigIdx) rtB.blockname[0] LibBlockInputSignal(0, "", lcv, sigIdx) u[i]
In the first example, LibBlockInputSignal
returns
rtB.blockname[2]
when the input port is connected to the output of
another block, and
The loop control variable (lcv
) generated by the
%roll
directive is empty, indicating that the current roll
region is below the roll threshold, and sigIdx
is
0
.
The width of the input port is 1
, indicating that this port
is being scalar expanded.
If sigIdx
is nonzero, then
rtB.blockname[sigIdx]
is returned. For example, if
sigIdx
is 3
, then
rtB.blockname[3]
is returned.
In the second example, LibBlockInputSignal
returns
u[i]
when the current roll region is above the roll threshold and the input
port width is nonscalar (wide). In this case, the Roller TLC file sets up a local
variable, u
, to point to the input signal, and the code in the
current %roll
directive is placed within a for
loop.
For another example, consider a block with multiple input ports where each port has a width greater than or equal to 1 and at least one port has width equal to 1. The following code sets the output signal to the sum of the squares of the input signals.
%assign y = LibBlockOutputSignal(0, "", "", 0) %<y> = 0; %assign rollVars = ["U"] %foreach port = block.NumDataInputPorts - 1 %roll sigIdx=RollRegions, lcv = RollThreshold, block, ... "Roller", rollVars %assign u = LibBlockInputSignal(port, "", lcv, sigIdx) %<y> += %<u> * %<u>; %endroll %endforeach
Because the first parameter of LibBlockInputSignal
is
0
indexed, you must index the foreach
loop to
start from 0
and end at
NumDataInputPorts-1
.
User Control Variable (ucv) Handling. This is an advanced mode and generally not required by S-function authors.
If ucv != ""
, LibBlockInputSignal
returns an
rvalue
for the input signal using the user control variable
indexing expression. The control variable indexing expression has the following form:
rvalue_id[%<ucv>]%<optional_real_or_imag_part>
To obtain rvalue_id
, look at the integer part of
sigIdx
. You must specify sigIdx
because the
input to this block can be discontinuous, meaning that the input can come from several
different memory areas (signal sources) and sigIdx
is used to
identify the area of interest for the ucv
. You can also use
sigIdx
to determine whether the real or imaginary part of a signal
is to be accessed.
You can obtain optional_real_or_imag_part
from the string part
of sigIdx
(i.e., "re"
, or "im"
,
or ""
).
Note that the value for lcv
is ignored and
sigIdx
must point to the same element in the input signal to which
the ucv
initially points.
The handling of ucv
with LibBlockInputSignal
requires care. Consider a discontinuous input signal feeding an input port as in the
following block diagram:
To use ucv
in a robust manner, you must use the
%roll
directive with a roll threshold of 1
and a
Roller TLC file that does not have loop header/trailer setup for this input signal. In
addition, you need to use ROLL_ITERATIONS
to determine the width of
the current roll region, as in the following TLC code:
{ int i; %assign rollVars = [""] %assign threshold = 1 %roll sigIdx=RollRegions, lcv=threshold, block, ... "FlatRoller", rollVars %assign u = LibBlockInputSignal( 0, "i", "", sigIdx) %assign y = LibBlockOutputSignal(0, "i+%<sigIdx>", "", sigIdx) %assign p = LibBlockParameter( 0, "i+%<sigIdx>", "", sigIdx) for (i = 0; i < %<ROLL_ITERATIONS()>; i++) { %<y> = %<p> * %<u>; } %endroll }
Note that the FlatRoller
does not have loop header/trailer setup
(rollVars
is ignored). Its purpose is to walk the
RollRegions
of the block. Alternatively, you can force a contiguous
input signal to your block by specifying
ssSetInputPortRequiredContiguous(S, port, TRUE)
in your S-function.
In this case, the TLC code simplifies to
{ %assign u = LibBlockInputSignal( 0, "i", "", 0) %assign y = LibBlockOutputSignal(0, "i", "", 0) %assign p = LibBlockParameter( 0, "i", "", 0) for (i = 0; i < %<LibBlockInputSignalWidth(0)>; i++) { %<y> = %<p> * %<u>; } }
If you create your own roller and the indexing does not conform to the way the
Roller TLC file provided by MathWorks operates, then must to use ucv
instead of lcv
.
Consider the following cases:
Function (Case 1, 2, 3,4) | Example Return Value |
---|---|
LibBlockInputSignal(0, "i", "", sigIdx) | rtB.blockname[i] |
LibBlockInputSignal(0, "i", "", sigIdx) | rtU.signame[i] |
LibBlockInputSignal(0, "", lcv, sigIdx) | u0[i1] |
LibBlockInputSignal(0, "", lcv, sigIdx) | rtB.blockname[0] |
The value returned depends on what the input signal is connected to in the block
diagram and how the function is invoked (e.g., in a %roll
or directly).
In the above example,
Cases 1 and 2 occur when an explicit call is made with the ucv
set to "i"
.
Case 1 occurs when sigIdx
points to the block I/O vector, i.e.,
the first element that "i"
starts with. For example, if you
initialize "i"
to be starting at offset 5
, then
you should specify sigIdx == 5
.
Case 2 occurs when sigIdx
points to the external input vector,
i.e., the first element that "i"
starts with. For example, if you
initialize "i"
to start at offset 20
, then you
should specify sigIdx == 20
.
Cases 3 and 4 receive the same arguments, lcv
and
sigIdx
; however, they produce different return values.
Case 3 occurs when LibBlockInputSignal
is called within a
%roll
directive and the current roll region is being rolled
(lcv != ""
).
Case 4 occurs when LibBlockInputSignal
is called within a
%roll
directive and the current roll region is not being rolled
(lcv == ""
).
When called within a%roll
directive,
LibBlockInputSignal
looks at ucv
,
lcv
, and sigIdx
, the current roll region, and the
current roll threshold to determine the return value. The variable ucv
has highest precedence, lcv
has the next highest precedence, and
sigIdx
has the lowest precedence. That is, if ucv
is specified, it is used (thus, when called in a %roll
directive it is
usually ""
). If ucv
is not specified, and if
lcv
and sigIdx
are specified, the returned value
depends on whether or not the current roll region is being placed in a
for
loop or being expanded. If the roll region is being placed in a
loop, then lcv
is used; otherwise, sigIdx
is
used.
A direct call to LibBlockInputSignal
(inside or outside a
%roll
directive) uses sigIdx
when
ucv
and lcv
are specified as
""
.
For an example of LibBlockInputSignal
, see sfun_multiport.tlc
.
See also blkiolib.tlc
.
Returns a string that provides the memory address of the specified block input port signal.
When you need an input signal address, you must use
LibBlockInputSignalAddr
instead of appending an
“&
” to the string returned by
LibBlockInputSignal
. For example,
LibBlockInputSignal
can return a literal constant, such as
5
(i.e., an invariant input signal). The code generator tracks when
LibBlockInputSignalAddr
is called on an invariant signal and declares
the signal as const
data (which is addressable), instead of being placed
as a literal constant in the generated code (which is not addressable).
Note that the last input argument, sigIdx
, is not overloaded, which
it is in LibBlockInputSignal
. Hence, if the input signal is complex, the
address of the complex container is returned.
To get the address of a wide input signal and pass it to a user function for processing, you could use
%assign uAddr = LibBlockInputSignalAddr(0, "", "", 0) %assign y = LibBlockOutputSignal(0, "", "", 0) %<y> = myfcn(%<uAddr>);
See LibBlockInputSignalAddr
in blkiolib.tlc
.
Returns the name of the aliased thru data type (e.g., int_T, ...
creal_T
) corresponding to the specified block input port. Specify the
reim
argument as ""
(empty) if you want the complete
signal type name.
For example, if reim
== ""
and the first output
port is real and complex, the data type name placed in dtname
is
creal_T
.
%assign dtname = LibBlockInputSignalDataTypeName(0,"")
Specify reim
as tRealPart
if you want the raw
element type name. For example, if reim
== tRealPart
and the first output port is real and complex, the data type name returned is
real_T
.
%assign dtname = LibBlockOutputSignalDataTypeName(0,tRealPart)
See LibBlockInputSignalAliasedThruDataTypeName
in blkiolib.tlc
.
Allow the input signal to be an expression, even when an output signal is wide. This
function takes the block record and the port index as input arguments. Call this function
from within the BlockInstanceSetup
function.
See LibBlockInputSignalAllowScalarExpandedExpr
in blkio_api.tlc
.
Returns the escaped name of the units corresponding to the specified block input port. This function takes the port index as an input argument.
See LibBlockInputSignalASCIIEscapedUnitExpr
in blkio_api.tlc
.
Returns 1 if the specified input port is connected to a block other than the Ground block and 0 otherwise.
See LibBlockInputSignalConnected
inblkio_api.tlc
.
Returns the numeric identifier (id
) corresponding to the data type of
the specified block input port.
If the input port signal is complex, LibBlockInputSignalDataTypeId
returns the data type of the real part (or the imaginary part) of the signal.
See LibBlockInputSignalDataTypeId
in blkiolib.tlc
.
Returns the name of the data type (e.g., int_T
, ...
creal_T
) corresponding to the specified block input port.
Specify the reim
argument as ""
if you want the
complete signal type name. For example, if reim==""
and the first output
port is real and complex, the data type name placed in dtname
is
creal_T
.
%assign dtname = LibBlockInputSignalDataTypeName(0,"")
Specify the reim
argument as tRealPart
if you want
the raw element type name. For example, if reim==tRealPart
and the first
output port is real and complex, the data type name returned is
real_T
.
%assign dtname = LibBlockInputSignalDataTypeName(0,tRealPart)
See LibBlockInputSignalDataTypeName
in blkiolib.tlc
.
Returns the dimensions vector of the specified block input port, e.g.,
[2,3]
.
See LibBlockInputSignalDimensions
in blkio_api.tlc
.
Returns 1 if the specified block input port is complex, 0 otherwise.
See LibBlockInputSignalIsComplex
in blkio_api.tlc
.
Returns 1 (true) if the input signal is an expression (versus a variable), and 0 (false) otherwise. This function takes the port index as an input argument.
See LibBlockInputSignalIsExpr
in blkio_api.tlc
.
Returns 1 if the specified block input port is frame based, 0 otherwise.
See LibBlockInputSignalIsFrameData
in blkio_api.tlc
.
Returns 1 (true) if the input signal is a trivial expression (versus a variable), and 0 (false) otherwise. This function take the port index as an input argument.
See LibBlockInputSignalIsTrivialExpr
in blkio_api.tlc
.
Returns the local sample time index corresponding to the specified block input port.
See LibBlockInputSignalLocalSampleTimeIndex
in blkiolib.tlc
.
Returns the number of dimensions of the specified block input port.
See LibBlockInputSignalNumDimensions
in blkio_api.tlc
.
Returns the offset time corresponding to the specified block input port.
See LibBlockInputSignalOffsetTime
in blkiolib.tlc
.
Returns the sample time corresponding to the specified block input port.
See LibBlockInputSignalSampleTime
in blkiolib.tlc
.
Returns the sample time index corresponding to the specified block input port.
See LibBlockInputSignalSampleTimeIndex
in blkiolib.tlc
.
Returns the number of dimensions of the specified block input port.
See LibBlockInputSignalSymbolicDimensions(portIdx)
in blkiolib.tlc
.
Returns the symbolic width of the specified block input port.
See LibBlockInputSignalSymbolicWidth(portIdx)
in blkiolib.tlc
.
Returns the width of the specified block input port index.
See LibBlockInputSignalWidth
in blkio_api.tlc
.
Returns the name of the units corresponding to the specified block input port. This function takes the port index as an input argument.
See LibBlockInputSignalUnitExpr
in blkio_api.tlc
.
Returns the numeric identifier (id) corresponding to the units of the specified block input port. This function takes the port index as an input argument.
See LibBlockInputSignalUnitId
in blkio_api.tlc
.
See also LibBlockInputSignalUnitExp
and
LibBlockOutputSignalUnitId
in blkio_api.tlc
.
Returns the number of data input ports of a block (excludes control ports).
See LibBlockNumInputPorts
in blocklib.tlc
.