Документация

Сведения о S-функциях C MEX

Можно создать S-функции C MEX, используя любой из следующих подходов:

Каждый из этих подходов включает в себя компромисс между простотой записи S-функции и признаками, поддерживаемыми S-функцией. Хотя написанные от руки S-функции поддерживают самый широкий спектр функций, их трудно записать. Блок S-Function Builder упрощает задачу записи C MEX S-функций, но поддерживает меньшее количество функций. Legacy Code Tool обеспечивает самый простой подход к созданию S-функций C MEX из существующего кода C, но поддерживает меньшее количество функций. Дополнительные сведения о функциях и ограничениях каждого из этих подходов к написанию S-функции C MEX см. в разделе Доступные реализации S-функций.

Если у вас есть Simulink Coder™, в дополнение к предыдущим трем подходам, продукт Simulink Coder предоставляет метод генерации C MEX S-функции из графической подсистемы. Если вы новичок в написании C MEX S-функций, вы можете построить части своего приложения в подсистеме Simulink и использовать S-функцию target для преобразования его в S-функцию. Сгенерированные файлы дают представление о том, как конкретные блоки могут быть реализованы в S-функции. Дополнительные сведения и ограничения по использованию цели S-функции см. в разделах Ускорение моделирования, повторное использование кода или Защита интеллектуальной собственности с помощью цели S-функции (Simulink Coder). Можно разработать S-функцию для представления внешнего кода с помощью API, который взаимодействует с механизмом Simulink. Используйте эту S-функцию с генератором кода для создания кода. Для получения подробной информации о различных типах S-функций при генерации кода см. S-Функции и генерация кода (Simulink Coder).

S-функция C MEX должна предоставлять информацию о функции механизму Simulink во время моделирования. По мере моделирования механизм, решатель ОДУ и S-функция C MEX взаимодействуют для выполнения конкретных задач. Эти задачи включают определение начальных условий и характеристик блоков, а также вычисления производных, дискретных состояний и выходных данных.

Как и в случае с S-функциями MATLAB, механизм Simulink взаимодействует с S-функцией C MEX путем вызова методов обратного вызова, реализуемых С-функцией. Каждый способ выполняет предопределенную задачу, такую как вычисление выходных сигналов блока, необходимую для моделирования блока, функциональность которого определяет S-функция. Однако S-функция может свободно выполнять задачу в каждом способе в соответствии с функциональными возможностями, которые реализует S-функция. Например, mdlOutputs метод должен вычислять выходные данные блока в текущее время моделирования. Однако S-функция может вычислять эти выходы любым способом, который подходит для функции. Этот API на основе обратного вызова позволяет создавать S-функции и, следовательно, пользовательские блоки любой требуемой функциональности.

Набор методов обратного вызова, который могут реализовать S-функции C MEX, больше, чем доступный для S-функций MATLAB. S-функции C MEX необходимы для реализации только небольшого подмножества методов обратного вызова в API S-функции. Если блок не реализует определенную функцию, например, матричные сигналы, вы можете опустить методы обратного вызова, необходимые для реализации функции. Это позволяет очень быстро создавать простые блоки.

Общий формат S-функции C MEX показан ниже:

#define S_FUNCTION_NAME  your_sfunction_name_here
#define S_FUNCTION_LEVEL 2
#include "simstruc.h"

static void mdlInitializeSizes(SimStruct *S)
{
}

<additional S-function routines/code>

static void mdlTerminate(SimStruct *S)
{
}
#ifdef MATLAB_MEX_FILE    /* Is this file being compiled as a 
                             MEX-file? */
#include "simulink.c"     /* MEX-file interface mechanism */
#else
#include "cg_sfun.h"      /* Code generation registration 
                             function */
#endif

mdlInitializeSizes является первой подпрограммой, вызываемой механизмом Simulink при взаимодействии с S-функцией. Движок впоследствии вызывает другие методы S-функций (все начиная с mdl). В конце моделирования механизм вызывает mdlTerminate.

Пример базовой S-функции C MEX

В этом разделе представлен пример C MEX S-функции, которую можно использовать в качестве модели для создания простых C S-функций. Пример S-функции timestwo.c выводит в два раза его вход.

В следующей модели используется timestwo S-функция для удвоения амплитуды синусоидальной волны и построения её графика в пределах.

Диалоговое окно блока для S-функции определяет timestwo в качестве имени S-функции; поле параметров пустое.

timestwo S-функция содержит методы обратного вызова S-функции, показанные на этом рисунке. В конце S-функции включите фрагмент кода, как описано в разделе Интерфейсы кодера Simulink/Simulink.

Содержание timestwo.c показаны ниже. Описание кода приводится после примера.

#define S_FUNCTION_NAME timestwo /* Defines and Includes */
#define S_FUNCTION_LEVEL 2

#include "simstruc.h"

static void mdlInitializeSizes(SimStruct *S)
{
    ssSetNumSFcnParams(S, 0);
    if (ssGetNumSFcnParams(S) != ssGetSFcnParamsCount(S)) {
        return; /* Parameter mismatch reported by the Simulink engine*/
    }

    if (!ssSetNumInputPorts(S, 1)) return;
    ssSetInputPortWidth(S, 0, DYNAMICALLY_SIZED);
    ssSetInputPortDirectFeedThrough(S, 0, 1);

    if (!ssSetNumOutputPorts(S,1)) return;
    ssSetOutputPortWidth(S, 0, DYNAMICALLY_SIZED);

    ssSetNumSampleTimes(S, 1);

    /* Take care when specifying exception free code - see sfuntmpl.doc */
    ssSetOptions(S, SS_OPTION_EXCEPTION_FREE_CODE);
    }

static void mdlInitializeSampleTimes(SimStruct *S)
{
    ssSetSampleTime(S, 0, INHERITED_SAMPLE_TIME);
    ssSetOffsetTime(S, 0, 0.0);
}

static void mdlOutputs(SimStruct *S, int_T tid)
{
    int_T i;
    InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);
    real_T *y = ssGetOutputPortRealSignal(S,0);
    int_T width = ssGetOutputPortWidth(S,0);

    for (i=0; i<width; i++) {
        *y++ = 2.0 *(*uPtrs[i]);
    }
}

static void mdlTerminate(SimStruct *S){}

#ifdef MATLAB_MEX_FILE /* Is this file being compiled as a MEX-file? */
#include "simulink.c" /* MEX-file interface mechanism */
#else
#include "cg_sfun.h" /* Code generation registration function */
#endif

Этот пример состоит из трех частей:

Определяет и включает

Пример начинается со следующего: define заявления.

#define S_FUNCTION_NAME  timestwo
#define S_FUNCTION_LEVEL 2

Первое define оператор задает имя S-функции (timestwo). Второе define оператор указывает, что S-функция находится в формате Level 2 (дополнительные сведения о Level 1 и Level 2 S-функциях см. в разделе Преобразование Level-1 C MEX S-функций).

После определения этих двух элементов пример включает simstruc.h, который является заголовочным файлом, предоставляющим доступ к SimStruct структура данных и функции прикладного программного интерфейса (API) MATLAB.

#define S_FUNCTION_NAME  timestwo
#define S_FUNCTION_LEVEL 2
#include "simstruc.h"

simstruc.h файл определяет структуру данных, называемую SimStruct, который механизм Simulink использует для поддержания информации о S-функции. simstruc.h файл также определяет макросы, которые позволяют файлу MEX устанавливать значения в и получать значения (например, входной и выходной сигнал в блоке) из SimStruct (см. раздел О функциях SimStruct).

Реализации метода обратного вызова

Следующая часть timestwo S-функция содержит реализации требуемых методов обратного вызова.

InputRealPtrsType uPtrs = ssGetInputPortRealSignalPtrs(S,0);

*uPtrs[i]

real_T *y = ssGetOutputPortRealSignal(S,0);

int_T width = ssGetOutputPortWidth(S,0);

Интерфейсы кодера Simulink/Simulink

В конце S-функции включите следующий код для присоединения S-функции к продуктам Simulink или Simulink Coder.

#ifdef MATLAB_MEX_FILE
#include "simulink.c"
#else
#include "cg_sfun.h"
#endif

Этот трейлер требуется в конце каждой S-функции. Если он опущен, любая попытка компиляции S-функции будет прервана с помощью failure during build of exports file сообщение об ошибке.

Построение примера Timestwo

Для компиляции этой S-функции введите

mex timestwo.c

в командной строке. mex команда компилирует и связывает timestwo.c с использованием компилятора по умолчанию. mex создает динамически загружаемый исполняемый файл для использования программой Simulink. При наличии нескольких компиляторов, поддерживаемых MATLAB, можно изменить значение по умолчанию с помощью mex -setup команда. См. раздел Изменение компилятора по умолчанию и список поддерживаемых компиляторов.

Результирующий исполняемый файл называется MEX S-функцией, где MEX обозначает «MATLAB Executable». "Расширение файла MEX зависит от платформы. Например, в 32-разрядной системе Microsoft ® Windows ^® расширение файла MEX имеет значение .mexw32.