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
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>;
%endrollWith 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
%endforeachBecause 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.