| Target Language Compiler | |
LibBlockInputSignal(portIdx, ucv, lcv, sigIdx)
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 appropriate 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, an external input, or it can be a literal constant (e.g, 5.0).
Since 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 may result in a reference to a literal constant (e.g., 5.0).
For example, the following would not work.
If %<u> refers to an invariant signal with a value of 4.95, the statement (after being processed by the pre-processor) would be generated as
or, if the input signal sources to ground, the statement could come out as
neither of these would compile.
Avoid any such situations by using LibBlockInputSignalAddr.
Real-Time Workshop tracks signals and parameters accessed by their address and declares them in addressable memory.
Input Arguments
The following table summarizes the input arguments to LibBlockInputSignal.
General Usage
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 non-empty value for lcv is only allowed 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 is appropriate for 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 always the starting index of the current roll region and lcv will be "" or an indexing variable. The following are examples of valid values:
In Example 1, LibBlockInputSignal returns rtB.blockname[2] when the input port is connected to the output of another block and:
lcv) generated by the %roll directive is empty, indicating that the current roll region is below the roll threshold and sigIdx is 0.
1, indicating that this port is being scalar expanded.
sigIdx was non-zero, then rtB.blockname[sigIdx] would be returned. For example if sigIdx was 3, then rtB.blockname[3] would be returned.
In Example 2, LibBlockInputSignal returns u[i] when the current roll region is above the roll threshold and the input port width is non-scalar (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, suppose we have 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 all 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
Since 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 needed 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 is obtained by looking at the integer part of sigIdx. Specifying sigIdx is required 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. Also, sigIdx is used to determine whether the real or imaginary part of a signal is to be accessed.
optional_real_or_imag_part is obtained by the string part of sigIdx (i.e. "re", or "im", or "").
Note: 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 has no 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, the FlatRoller has no 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
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 < %<DataInputPort[0].Width>; 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 the MathWorks operates, then you will need to use ucv instead of lcv.
Input Arguments (ucv, lcv, and sigIdx) Handling
Consider the following cases :
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:
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 pointing to the external input vector, i.e., the first element that "i" starts with. For example, if you initialize "i" to be starting at offset 20, then you should specify sigIdx == 20.
lcv and sigIdx, however, they produce different return values.
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, this function 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 will be used (thus, when called in a %roll directive it is usually ""). If ucv is not specified and 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 this function (inside or outside of a %roll directive) will use sigIdx when ucv and lcv are specified as "".
For an example of this function, see matlabroot/toolbox/simulink/blocks/tlc_c/sfun_multiport.tlc. See also matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
LibBlockInputSignalAddr(portIdx, ucv, lcv, sigIdx)
Returns the appropriate string that provides the memory address of the specified block input port signal.
When you need an input signal address, you must use this function 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). Real-Time Workshop 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, unlike LibBlockInputSignal(), the last input argument, sigIdx, is not overloaded. Hence, if the input signal is complex, the address of the complex container is returned.
Example
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 function in matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
LibBlockInputSignalConnected(portIdx)
Returns 1 if the specified input port is connected to a block other than the Ground block and 0 otherwise.
See function in matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
LibBlockInputSignalDataTypeId(portIdx)
Returns the numeric identifier (id) corresponding to the data type of the specified block input port.
If the input port signal is complex, this function returns the data type of the real part (or the imaginary part) of the signal.
See function in matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
LibBlockInputSignalDataTypeName(portIdx, reim)
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 will be creal_T.
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 will be real_T.
See function in matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
LibBlockInputSignalDimensions(portIdx)
Returns the dimensions vector of specified block input port, e.g., [2,3].
See function in matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
LibBlockInputSignalIsComplex(portIdx)
Returns 1 if the specified block input port is complex, 0 otherwise.
See function in matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
LibBlockInputSignalIsFrameData(portIdx)
Returns 1 if the specified block input port is frame based, 0 otherwise.
See function in matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
LibBlockInputSignalLocalSampleTimeIndex(portIdx)
Returns the local sample time index corresponding to the specified block input port.
See function in matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
LibBlockInputSignalNumDimensions(portIdx)
Returns the number of dimensions of the specified block input port.
See function in matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
LibBlockInputSignalOffsetTime(portIdx)
Returns the offset time corresponding to the specified block input port.
See function in matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
LibBlockInputSignalSampleTime(portIdx)
Returns the sample time corresponding to the specified block input port.
See function in matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
LibBlockInputSignalSampleTimeIndex(portIdx)
Returns the sample time index corresponding to the specified block input port.
See function in matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
LibBlockInputSignalWidth(portIdx)
Returns the width of the specified block input port index.
See function in matlabroot/rtw/c/tlc/lib/blkiolib.tlc.
| | Target Language Compiler Functions | Output Signal Functions | |