Writing S-Functions

ssSetOptions

Specify S-function options

Syntax

• void ssSetOptions(SimStruct *S, uint_T options)
  

Arguments

S
   SimStruct representing an S-Function block.

options
   Options.

Description

Use in mdlInitializeSizes to specify S-function options (see following). The options must be joined using the OR operator. For example:

• ssSetOptions(S, (SS_OPTION_EXCEPTION_FREE_CODE |
                  SS_OPTION_DISCRETE_VALUED_OUTPUT));
  

S-Function Options

An S-function can specify the following options, using ssSetOptions:

• SS_OPTION_EXCEPTION_FREE_CODE

• If your S-function does not use mexErrMsgTxt, mxCalloc, or any other routines that can throw an exception when called, you can set this option for improved performance.

• SS_OPTION_RUNTIME_EXCEPTION_FREE_CODE

• Similar to SS_OPTION_EXCEPTION_FREE_CODE except it only applies to the run-time routines mdlGetTimeOfNextVarHit, mdlOutputs, mdlUpdate, and mdlDerivatives.

• SS_OPTION_DISCRETE_VALUED_OUTPUT

• Specify this if your S-function has discrete valued outputs. This is checked when your S-function is placed within an algebraic loop. If your S-function has discrete valued outputs, its outputs are not assigned algebraic variables.

• SS_OPTION_PLACE_ASAP

• Use to specify that your S-function should be placed as soon as possible. This is typically used by devices connecting to hardware.

• SS_OPTION_ALLOW_INPUT_SCALAR_EXPANSION

• Use to specify that the input to your S-function input ports can be either 1 or the size specified by the port, which is usually referred to as the block width.

• SS_OPTION_DISALLOW_CONSTANT_SAMPLE_TIME

• Use to disable an S-Function block from inheriting a constant sample time.

• SS_OPTION_ASYNCHRONOUS

• This option applies only to S-functions that have 0 or 1 input ports and 1 output port. The output port must be configured to perform function calls on every element. If any of these requirements is not met, the SS_OPTION_ASYNCHRONOUS option is ignored. Use this option when driving function-call subsystems to attached to interrupt service routines.

• SS_OPTION_ASYNC_RATE_TRANSITION

• Use this option to create a read-write pair of blocks intended to guarantee correct data transfers between a synchronously and an asynchronously executing subsystem or between two asynchronously executing subsystems. Both your "read" S-function and your "write" S-function should set this option. See the comment for SS_OPTION_ASYNC_RATE_TRANSITION in symstruc.h for more information.

• SS_OPTION_PORT_SAMPLE_TIMES_ASSIGNED

• Use this when you have registered multiple sample times (ssSetNumSampleTimes > 1) to specify the rate at which each input and output port is running. The simulation engine needs this information when checking for illegal rate transitions.

• SS_OPTION_SFUNCTION_INLINED_FOR_RTW

• Set this if you have a .tlc file for your S-function and do not have an mdlRTW method. Setting this option has no effect if you have an mdlRTW method.

• SS_OPTION_ALLOW_PARTIAL_DIMENSIONS_CALL

• Indicates that the S-function can handle dynamically dimensioned signals. See mdlSetDefaultPortDimensionInfo for more information.

• SS_OPTION_FORCE_NONINLINED_FCNCALL

• Use this flag if the block requires that all function-call subsystems that it calls should be generated as procedures instead of possibly being generated as inlined code.

• SS_OPTION_USE_TLC_WITH_ACCELERATOR

• Use this option to force the Simulink Accelerator to use the TLC inlining code for an S-function, which speeds up execution of the S-function. If this option is not set, the Accelerator uses the mex version of the S-function even if a TLC file for the S-function exists. This option should not be set for device driver blocks (A/D) or when there is an incompatibility between running the mex Start/InitializeConditions functions together with the TLC Outputs/Update/Derivatives.

Note    The Simulink Accelerator does not require the Real-Time Workshop to be installed to run an inlined S-function. However, to ensure that the inlined S-function can run in accelerated mode in the current and future Simulink releases, the TLC file for the S-function must use documented TLC functions to access the CompiledModel structure.

• SS_OPTION_SIM_VIEWING_DEVICE

• This S-function is a SimViewingDevice. As long as it meets the other requirements for this type of block (no states, no outputs, etc.), it is considered to be an external mode block (it show up in the external mode GUI and no code is generated for it). During an external mode simulation, this block is run on the host only.

• SS_OPTION_CALL_TERMINATE_ON_EXIT

• This option allows S-function authors to better manage the data cached in run-time parameters and UserData. Setting this option guarantees that the mdlTerminate function is called if mdlInitializeSizes is called. This means that mdlTerminate is called
  • When a simulation ends

  • Note that it does not matter if the simulation fails and at what stage the simulation fails. Therefore, if the mdlSetWorkWidths of some block errors out, the model's other blocks have a chance to free the memory during a call to mdlTerminate.

  • Every time an S-Function block is destroyed
  • If the user is editing the S-function graphically
  • If the S-Function block was reduced as a result of invoking ssSetBlockReduction

  If this option is not set, mdlTerminate is called only if at least one of the blocks has had its mdlStart called.

• SS_OPTION_REQ_INPUT_SAMPLE_TIME_MATCH

• Use this to option to specify that the input signal sample times match the sample time assigned to the block input port. For example:
  
  

  generates an error if this option is set. If the block (or input port) sample time is inherited, no error is generated.

• SS_OPTION_WORKS_WITH_CODE_REUSE

• Signifies that this S-function is compatible with the subsystem code reuse feature of the Real-Time Workshop (see Creating Code-Reuse-Compatible S-Functions).

• SS_OPTION_ALLOW_CONSTANT_PORT_SAMPLE_TIME

• Set this option in mdlInitializeSizes to allow your S-function's ports to specify or inherit a constant sample time (see Specifying Constant Sample Time for a Port for more information).

• SS_OPTION_CAN_BE_CALLED_CONDITIONALLY

• Use this option if the S-function can be called conditionally by other blocks.

• SS_OPTION_ALLOW_PORT_BASED_SAMPLE_TIME_IN_TRIGSS

• Set this option in mdlInitializeSizes to allow an S-function that uses port-based sample times to operate in a triggered subsystem (see Configuring Port-Based Sample Times for Use in Triggered Subsystems for more information).

• SS_OPTION_NONVOLATILE

• Use this option to specify if this S-function has side effects. Set this option to enable Simulink to remove this block if it is not needed (dead branch elimination). See Block reduction optimization for further details.

Languages

C, C++

ssSetOneBasedIndexOutputPort

ssSetOutputPortComplexSignal

© 1994-2005 The MathWorks, Inc.