Input Signal Functions

LibBlockInputHasSymbolicWidth(portIdx)

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.

LibBlockInputPortIndexMode(block, pidx)

Purpose

Determines the index mode of a block's input port.

Arguments

block — Block record

pidx — Port index

Returns

"" for a nonindex port, and "Zero-based" or "One-based" otherwise.

Description

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.rtw file. LibBlockInputPortIndexMode queries the indexing base to branch to different code according to what the input port indexing base is.

Example

%if LibBlockInputPortIndexMode(block, pidx) == "Zero-based"
  ...
%elseif LibBlockInputPortIndexMode(block, pidx) == "One-based"
  ...
%else
  ...
%endif

See LibBlockInputPortIndexMode in blkiolib.tlc.

LibBlockInputPortIsContinuousQuantity(portIdx)

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.

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 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.

Input Arguments

The following table summarizes the input arguments to LibBlockInputSignal.

LibBlockInputSignal Arguments

ArgumentDescription

portIdx

Integer specifying the input port index (zero-based).

Note: For certain built-in blocks, portIdx can be a string identifying the port (such as "enable" or "trigger").

ucv

User control variable. Must be a string, either an indexing expression or "".

lcv

Loop control variable. Must be a string, either an indexing expression or "".

sigIdx

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"

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 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.

Handling Input Arguments: ucv, lcv, and sigIdx

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.

LibBlockInputSignalAddr(portIdx, ucv, lcv, sigIdx)

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.

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 LibBlockInputSignalAddr in blkiolib.tlc.

LibBlockInputSignalAliasedThruDataTypeName
(portIdx, reim)

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.

LibBlockInputSignalAllowScalarExpandedExpr(block,portIdx)

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.

LibBlockInputSignalASCIIEscapedUnitExpr(portIdx)

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.

LibBlockInputSignalConnected(portIdx)

Returns 1 if the specified input port is connected to a block other than the Ground block and 0 otherwise.

See LibBlockInputSignalConnected in blkio_api.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, LibBlockInputSignalDataTypeId returns the data type of the real part (or the imaginary part) of the signal.

See LibBlockInputSignalDataTypeId in 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 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.

LibBlockInputSignalDimensions(portIdx)

Returns the dimensions vector of the specified block input port, e.g., [2,3].

See LibBlockInputSignalDimensions in blkio_api.tlc.

LibBlockInputSignalIsComplex(portIdx)

Returns 1 if the specified block input port is complex, 0 otherwise.

See LibBlockInputSignalIsComplex in blkio_api.tlc.

LibBlockInputSignalIsExpr(portIdx)

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.

LibBlockInputSignalIsFrameData(portIdx)

Returns 1 if the specified block input port is frame based, 0 otherwise.

See LibBlockInputSignalIsFrameData in blkio_api.tlc.

LibBlockInputSignalIsTrivialExpr(portIdx)

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.

LibBlockInputSignalLocalSampleTimeIndex
(portIdx)

Returns the local sample time index corresponding to the specified block input port.

See LibBlockInputSignalLocalSampleTimeIndex in blkiolib.tlc.

LibBlockInputSignalNumDimensions(portIdx)

Returns the number of dimensions of the specified block input port.

See LibBlockInputSignalNumDimensions in blkio_api.tlc.

LibBlockInputSignalOffsetTime(portIdx)

Returns the offset time corresponding to the specified block input port.

See LibBlockInputSignalOffsetTime in blkiolib.tlc.

LibBlockInputSignalSampleTime(portIdx)

Returns the sample time corresponding to the specified block input port.

See LibBlockInputSignalSampleTime in blkiolib.tlc.

LibBlockInputSignalSampleTimeIndex(portIdx)

Returns the sample time index corresponding to the specified block input port.

See LibBlockInputSignalSampleTimeIndex in blkiolib.tlc.

LibBlockInputSignalSymbolicDimensions(portIdx)

Returns the number of dimensions of the specified block input port.

See LibBlockInputSignalSymbolicDimensions(portIdx) in blkiolib.tlc.

LibBlockInputSignalSymbolicWidth(portIdx)

Returns the symbolic width of the specified block input port.

See LibBlockInputSignalSymbolicWidth(portIdx) in blkiolib.tlc.

LibBlockInputSignalUnitExpr(portIdx)

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.

LibBlockInputSignalUnitId(portIdx)

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.

LibBlockInputSignalValue(portIdx, sigIdx)

Returns the parameter value of the Constant block connected to the input port of a block, based on the input port number (portIdx) and the signal index (sigIdx) of the Constant block.

The following table summarizes the input arguments to LibBlockInputSignalValue.

ArgumentDescription
portIdx

Input port number (Zero-based) of the current block, specified as an integer.

sigIdx

Signal index of the Constant block, specified as an integer literal.

To retrieve the parameter value for an input port using the function LibBlockInputSignalValue, the specified input port must be connected to a Constant block and the model configuration parameter Default parameter behavior must be set to Inlined. The function produces an error if these conditions are not satisfied.

Note

Prefer using block parameters over the function LibBlockInputSignalValue to access Constant block values.

See LibBlockInputSignalValue in blkio_api.tlc.

LibBlockInputSignalWidth(portIdx)

Returns the width of the specified block input port index.

See LibBlockInputSignalWidth in blkio_api.tlc.

LibBlockNumInputPorts(block)

Returns the number of data input ports of a block (excludes control ports).

See LibBlockNumInputPorts in blocklib.tlc.

See Also

Topics