s_function_ch.c

matlab中simulink中用C语言编写S函数模板的翻译版本

 *    直接反馈标志可以是1＝yes或者0＝no。如果输入"u"在mdlOutput函数体内被使用，其应被设置为1。
 *    类似的如果"u"确定不会在上述函数体内使用，其应被设置为0。但是如果在这种情况下违反了
 *    限制，未知的情况会发生。
 *
 *    The NumContStates, NumDiscStates, NumInputs, NumOutputs, NumRWork,
 *    NumIWork, NumPWork NumModes, 和 NumNonsampledZCs宽度可以被设置为:
 *       DYNAMICALLY_SIZED    - 在这种情况下，他们被设置为实际的输入的输入宽度，除非mdlSetWorkWidths设置
 *                              宽度。
 *       0或者任意正整数       - 确切定义各项的值。
 */
static void mdlInitializeSizes(SimStruct *S)
{
    int_T nInputPorts  = 1;  /* 输入端口的个数 */
    int_T nOutputPorts = 1;  /* 输出端口的个数 */
    int_T needsInput   = 1;  /* 直接反馈标志    */

    int_T inputPortIdx  = 0;
    int_T outputPortIdx = 0;


    ssSetNumSFcnParams(S, 0);  /* 期望的参数个数 */
    if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) {
        /*
         * 如果在对话框中返回的参数个数不同于合法的参数个数，Simulink将产生一个
         * 标志参数不匹配的错误
         */
        return;
    }

    /* 
     * 配置参数的可能性。默认情况下，所有的参数都是在仿真过程中可以修改的、
     * 如果有参数在仿真的过程中不能被修改。例如参数修改端口的个数，端口的采样时间
     * 信号数据类型，通过一个调用标志这些： 
     *   
     *      ssSetSFcnParamTunable(S, 0, 0);
     *  以上命令将参数0设置为不可调(0).   
     */

     /* 记录S-function使用状态的类型和个数*/

    ssSetNumContStates(    S, 0);   /* 连续状态的个数           */
    ssSetNumDiscStates(    S, 0);   /* 离散状态的个数             */


    /*
     * 配置输入端口，首先设置输入端口的个数. 
     */
    if (!ssSetNumInputPorts(S, nInputPorts)) return;    
    /*
     *  设置端口的维数的索引从0开始，以下的几个选项总结了不同的方法设置输入端口的维度。
     *
     * (1) 如果输入端口的维数未知，使用
     *     ssSetInputPortDimensionInfo(S, inputPortIdx, DYNAMIC_DIMENSION))
     *
     * (2) 如果输入的信号是非取向的并且宽度是使用
     *     ssSetInputPortVectorDimension(S, inputPortIdx, w)
     *     w (或者width) 可以是 DYNAMICALLY_SIZED或者比0大的数.
     *     等效于 ssSetInputPortWidth(S, inputPortIdx, w).
     *
     * (3) 如果输入的信号是一个mxn维的矩阵使用 
     *     ssSetInputPortMatrixDimensions(S, inputPortIdx, m, n)
     *     m和n可以是DYNAMICALLY_SIZED或者比零大的数.
     *
     * (4) 否则使用:
     *     ssSetInputPortDimensionInfo(S, inputPortIdx, dimsInfo)
     *     这个函数可以用来全部或这局部的初始端口的维度。dimsInfo是一个结构体包含宽度，维度个数，以及端口的维数.
     */
    if(!ssSetInputPortDimensionInfo(S, inputPortIdx, DYNAMIC_DIMENSION)) return;
    
    /*
     * 设置直接反馈的标志(1=yes, 0=no).
     * 一个端口有直接反馈如果输入在mdlOutputs或者mdlGetTimeOfNextVarHit中使用时。
     * 查看 matlabroot/simulink/src/sfuntmpl_directfeed.txt.
     */
    ssSetInputPortDirectFeedThrough(S, inputPortIdx, needsInput);

    /*
     * 配置输出端口，首先设置输出端口的个数
     */
    if (!ssSetNumOutputPorts(S, nOutputPorts)) return;

    /*
     * 设置每个输出端口的维度索引从0开始
     * 查看输入端口的维度.
     */
    if(!ssSetOutputPortDimensionInfo(S,outputPortIdx,DYNAMIC_DIMENSION)) return;

    /*
     * 设置采样时间的个数。必须是个正整数或者PORT_BASED_SAMPLE_TIMES。对于多速率的S-functions
     * 推荐方法是通过端口为基准时间方法。
     */
    ssSetNumSampleTimes(   S, 1);   /*采样时间的个数             */

    /*
     * 设置工作向量的大小尺寸
     */
    ssSetNumRWork(         S, 0);   /* real 工作向量元素的个数  */
    ssSetNumIWork(         S, 0);   /* integer工作向量元素的个数*/
    ssSetNumPWork(         S, 0);   /* 指针型工作向量元素的个数 */
    ssSetNumModes(         S, 0);   /* mode工作向量元素的个数     */
    ssSetNumNonsampledZCs( S, 0);   /* 未被采样零相交的个数   */

    /*
     * 所有的选项形似于SS_OPTION_<name>在matlabroot/simulink/include/simstruc.h中有描述. 
     * 这些选项都是bit域的，可以通过位或来一起设置
     *   ssSetOptions(S, (SS_OPTION_name1 | SS_OPTION_name2))
     */

    ssSetOptions(          S, 0);   /* 一般设置(SS_OPTION_xx)        */

} /* mdlInitializeSizes 结束 */


#define MDL_SET_INPUT_PORT_FRAME_DATA  /*  #undef移除函数*/
#if defined(MDL_SET_INPUT_PORT_FRAME_DATA) && defined(MATLAB_MEX_FILE)
  /* 函数: mdlSetInputPortFrameData ========================================
   * 摘要:
   *    该方法对输入端口帧类型设置(FRAME_YES, or
   *    FRAME_NO) 。 如果推荐的设置是可以接受的，该方法首先设置实际的帧类型，用 
   *    ssSetInputPortFrameData(S,portIndex,frameData)。  如果设置是不可接受的，
   *    一个用ssSetErrorStatus错误将发生。注意所有帧数据类型由已知给定端口潜在定义的动态帧输入或输出端口，
   *    可由ssSetInputPortFrameData和ssSetOutputPortFrameData再定义。
   */
   static void mdlSetInputPortFrameData(SimStruct *S, 
                                        int       portIndex, 
                                        Frame_T   frameData)
  {
  } /* 结束mdlSetInputPortFrameData */
#endif /* MDL_SET_INPUT_PORT_FRAME_DATA */


#define MDL_SET_INPUT_PORT_WIDTH   /* #undef去掉函数*/
#if defined(MDL_SET_INPUT_PORT_WIDTH) && defined(MATLAB_MEX_FILE)
  /* Function: mdlSetInputPortWidth ===========================================
   * Abstract:
   *       该方法用于动态大小的端口设置。如果推荐端口宽度可接受，该方法首先通过ssSetInputPortWidth
   *       设置实际端口的的宽度。否则，不接受，则由ssSetErrorStatus报错。
   *       可强制设置某个端口的大小由 ssSetInputPortWidth或者ssSetOutputPortWidth。
   */
  static void mdlSetInputPortWidth(SimStruct *S, int portIndex, int width)
  {
  } /* 结束mdlSetInputPortWidth */
#endif /* MDL_SET_INPUT_PORT_WIDTH */


#define MDL_SET_OUTPUT_PORT_WIDTH   /*  #undef 去掉函数*/
#if defined(MDL_SET_OUTPUT_PORT_WIDTH) && defined(MATLAB_MEX_FILE)
   /* Function: mdlSetOutputPortWidth ===========================================
   * Abstract:
   *       该方法用于动态大小的端口设置。如果推荐端口宽度可接受，该方法首先通过ssSetInputPortWidth
   *       设置实际端口的的宽度。否则，不接受，则由ssSetErrorStatus报错。
   *       可强制设置某个端口的大小由 ssSetInputPortWidth或者ssSetOutputPortWidth。
   */
  static void mdlSetOutputPortWidth(SimStruct *S, int portIndex, int width)
  {
  } /* 结束mdlSetOutputPortWidth */
#endif /* MDL_SET_OUTPUT_PORT_WIDTH */


#undef MDL_SET_INPUT_PORT_DIMENSION_INFO /*  #define 添加函数 */
#if defined(MDL_SET_INPUT_PORT_DIMENSION_INFO) && defined(MATLAB_MEX_FILE)
  /* Function: mdlSetInputPortDimensionInfo ===========================================
   * Abstract:
   *       该方法用于未知维度的端口维度设置。如果推荐端口维度可接受，该方法首先设置实际端口的维度
   *       设置实际端口的的宽度。否则，不接受，则由ssSetErrorStatus报错。
   *       即使，某端口通过其他已设置端口的影响，但仍可强制设置某个端口的维度设置。
   *
   *       查看See matlabroot/simulink/src/sfun_matadd.c
   */
  static void mdlSetInputPortDimensionInfo(SimStruct        *S,         
                                           int_T            portIndex,
                                           const DimsInfo_T *dimsInfo)
  {
  } /* mdlSetInputPortDimensionInfo */
#endif /* MDL_SET_INPUT_PORT_DIMENSION_INFO */


#undef MDL_SET_OUTPUT_PORT_DIMENSION_INFO /*  #define添加函数*/
#if defined(MDL_SET_OUTPUT_PORT_DIMENSION_INFO) && defined(MATLAB_MEX_FILE)
   /* Function: mdlSetOutputPortDimensionInfo ===========================================
   * Abstract:
   *       该方法用于未知维度的端口维度设置。如果推荐端口维度可接受，该方法首先设置实际端口的维度
   *       设置实际端口的的宽度。否则，不接受，则由ssSetErrorStatus报错。
   *       即使，某端口通过其他已设置端口的影响，但仍可强制设置某个端口的维度设置。
   *
   *       查看See matlabroot/simulink/src/sfun_matadd.c
   */
  static void mdlSetOutputPortDimensionInfo(SimStruct        *S,        
                                            int_T            portIndex,
                                            const DimsInfo_T *dimsInfo)
  {
  } /* mdlSetOutputPortDimensionInfo */
#endif /* MDL_SET_OUTPUT_PORT_DIMENSION_INFO */


#undef MDL_SET_DEFAULT_PORT_DIMENSION_INFO /* #define 添加函数*/
#if defined(MDL_SET_DEFAULT_PORT_DIMENSION_INFO) && defined(MATLAB_MEX_FILE)
  /* 函数体: mdlSetDefaultPortDimensionInfo ==================================
   * Abstract:
   *    这个方法用在没有足够的信息分别定义每个端口维度的模型中。一旦使用，
   *    Simulink的维度扩散引擎将调用这个函数请求将任何输出和输入端口维度设置为动态大小
   *
   *    如果你提供该方法，并且有动态大小的端口Simulink没有足够的信息来传递维度给 S-function。
   *    Simulink将设置这些未知的端口的维度为'block width'取决于任一个已知的端口。
   *    如果没有已知，宽度将被设置为1
   * 
   *    查看matlabroot/simulink/src/sfun_matadd.c。 
   */
  static void mdlSetDefaultPortDimensionInfo(SimStruct *S)
  {
  } /* mdlSetDefaultPortDimensionInfo */
#endif /* MDL_SET_DEFAULT_PORT_DIMENSION_INFO */


#define MDL_SET_INPUT_PORT_SAMPLE_TIME
#if defined(MDL_SET_INPUT_PORT_SAMPLE_TIME) && defined(MATLAB_MEX_FILE)
  /* 函数: mdlSetInputPortSampleTime =======================================
   * 摘要:
   *    这个方法对一个继承采样输入端口被调用。如果推荐的采样时间可以接受，方法首先设置端口
   *    实际的采样时间通过ssSetInputPortSampleTime。否则，不可接受，ssSetErrorStatus
   *    将产生错误。如果其他的被已有既定采样时间的端口(受其他已知端口的影响)，也可由
   *    ssSetInputPortSampleTime和ssSetOutputPortSampleTime设置它们的采样时间。
   *    
   *
   *    如果继承的端口时间定义后，采样时间为下者之一:
   *                    [sampleTime, offsetTime]
   *       continuous   [0.0       , 0.0       ]
   *       discrete     [period    , offset    ]  其中 0.0 < 周期 < inf
   *                                                    0.0 <= offset < 周期
   *    常数，触发和可变step采样时间不会借由端口 based sample times传递给S-functions。
   *    
   *    通常mdlSetInputPortSampleTime和mdlSetOutputPortSampleTime仅会被调用一次，
   *    不过也有情况下调用几次。当连续的采样时间被仿真引擎转为虽然是连续但是实际上为较小的
   *    step采样时间发生上述情况。原来在mdlInitializeSizes中定义的采样时间会被保存后又一次调用该方法。
   *    
   *    最终每个不同的端口可能有不同的采样时间(实际上等价)。当
   *    o) 采用一个固定的step solver和拥有连续被修正为有最小采样时间的端口。在这种情况下
   *       采样时间被转化为这个模型基本的采样时间 。
   *    o) 我们为了保证数值正确性调整采样时间。例如[0.2499999999999, 0]到[0.25,0]
   */
  static void mdlSetInputPortSampleTime(SimStruct *S,
                                        int_T     portIdx,
                                        real_T    sampleTime,
                                        real_T    offsetTime)
  {
  } /* 结束mdlSetInputPortSampleTime */
#endif /* MDL_SET_INPUT_PORT_SAMPLE_TIME */


#define MDL_SET_OUTPUT_PORT_SAMPLE_TIME
#if defined(MDL_SET_OUTPUT_PORT_SAMPLE_TIME) && defined(MATLAB_MEX_FILE)
  /* 函数体: mdlSetOutputPortSampleTime ======================================
   * 摘要:
   *    这个方法是在一个继承采样时间的输出端口使用。如果推荐的采样时间可以接受，方法首先设置端口
   *    实际的采样时间通过ssSetInputPortSampleTime。否则，不可接受，ssSetErrorStatus
   *    将产生错误。如果其他的被已有既定采样时间的端口(受其他已知端口的影响)，也可由
   *    ssSetInputPortSampleTime和ssSetOutputPortSampleTime设置它们的采样时间。
   *    
   *    一般来讲，采样时间由前面传递过来。尽管如此，如果源反馈给模块有继承的采样时间。
   *    Simulink可能选择由后传递过来。
   *   
   *   当这种方法被调用时，查看 mdlSetInputPortSampleTimes获取更多的信息。
   */
  static void mdlSetOutputPortSampleTime(SimStruct *S,
                                         int_T     portIdx,
                                         real_T    sampleTime,
                                         real_T    offsetTime)
  {
  } /* 结束mdlSetOutputPortSampleTime */
#endif /* MDL_SET_OUTPUT_PORT_SAMPLE_TIME */


/* 函数: mdlInitializeSampleTimes =========================================
 * 摘要:
 *
 *    这个函数用来定义S-function的采样时间。必须记录在ssSetNumSampleTimes中
 *    定义的采样时间的个数。如果没有定义采样时间，S-function被定义为有一个继承的
 *    采样时间。
 *
 *    采样时间由以下宏的方式成对定义为"[sample_time, offset_time]"
 *      ssSetSampleTime(S, sampleTimePairIndex, sample_time)
 *      ssSetOffsetTime(S, offsetTimePairIndex, offset_time)
 *    其中 sampleTimePairIndex 从0开始。
 *
 *    有效的采样时间对是(大写的值是在simstruc.h中宏定义的):
 *
 *      [CONTINUOUS_SAMPLE_TIME,  0.0                       ]
 *      [CONTINUOUS_SAMPLE_TIME,  FIXED_IN_MINOR_STEP_OFFSET]
 *      [discrete_sample_period,  offset                    ]