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

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

Создать S-функции C MEX можно с помощью любого из следующих подходов:

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

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

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

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

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

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

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

Представление примера базовой функции MEX S на C

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

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

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

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

Содержимое 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 (для получения дополнительной информации о S-функциях уровня 1 и уровня 2 см. раздел «Преобразование Level-1 C MEX S-Functions»).

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

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

The simstruc.h файл определяет структуру данных, называемую SimStruct, который механизм Simulink использует для поддержания информации о S-функции. The 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 Coder

В конце 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

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

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