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

Выберите C API with Configuration Parameters Dialog

Выберите C API из командной строки

Из командной строки MATLAB^® можно использовать функцию set_param, чтобы выбрать или снять флажки C API на панели Interface диалогового окна Configuration Parameters. В командной строке MATLAB введите один или несколько следующих команд, где modelname является именем вашей модели.

Выбрать Generate C API for: signals, введите:

set_param('modelname','RTWCAPISignals','on')

Очистить Generate C API for: signals, введите:

set_param('modelname','RTWCAPISignals','off')

Выбрать Generate C API for: parameters, введите:

set_param('modelname','RTWCAPIParams','on')

Очистить Generate C API for: parameters, введите:

set_param('modelname','RTWCAPIParams','off')

Выбрать Generate C API for: states, введите:

set_param('modelname','RTWCAPIStates','on')

Очистить Generate C API for: states, введите:

set_param('modelname','RTWCAPIStates','off')

Выбрать Generate C API for: root-level I/O, введите:

set_param('modelname','RTWCAPIRootIO','on')

Очистить Generate C API for: root-level I/O, введите:

set_param('modelname','RTWCAPIRootIO','off')

О файлах API C

model_capi.c (или .cpp) файл предоставляет внешним приложениям сопоставимый интерфейс к данным модели. В зависимости от ваших параметров конфигурации данные могли быть сигналом, состоянием, вводом или выводом корневого уровня или параметром. В этом документе термин data item относится или к сигналу, состоянию, вводу или выводу корневого уровня или к параметру. API C использует структуры, которые обеспечивают интерфейс к свойствам элемента данных. Интерфейсные пакеты свойства каждого элемента данных в структуре данных. Если модель содержит несколько элементов данных, интерфейс генерирует массив структур данных. Члены структуры данных сопоставляют со свойствами данных.

Чтобы взаимодействовать через интерфейс с элементами данных, приложение требует следующих свойств для каждого элемента данных:

Как проиллюстрировано в следующей фигуре, свойства элемента данных A, например, расположены в структуре данных DS_A. Свойства элемента данных B расположены в структуре данных DS_B.

Некоторые значения свойств могут быть уникальны для каждого элемента данных, и существуют некоторые значения свойств, которые несколько элементов данных могут совместно использовать вместе. Назовите, например, имеет уникальное значение для каждого элемента данных. Интерфейс помещает значения уникального свойства непосредственно в структуру для элемента данных. Значение имени элемента данных A находится в DS_A, и значение имени элемента данных B находится в DS_B.

Но тип данных мог быть свойством, значение которого несколько элементов данных имеют общего. Способность некоторых элементов данных совместно использовать свойство позволяет API C иметь функцию повторного использования. В этом случае интерфейс помещает только индексное значение в DS_A и индексное значение в DS_B. Эти индексы указывают на различную структуру данных, DS_C, который содержит фактическое значение типа данных. Следующие данные показывают эту схему с большим количеством детали.

Данные показывают три сигнала. signal1 и signal2 совместно используют совпадающий тип данных, double. Вместо того, чтобы задать это значение типа данных в каждой структуре данных сигнала, интерфейс обеспечивает только индексное значение, 0, в структуре. "double" описан записью 0 в массиве rtDataTypeMap, на который ссылаются оба сигнала. Кроме того, значения свойств могут быть совместно использованы сигналами, состояниями, входными параметрами/выходными параметрами корневого уровня и параметрами, так состояния, входные параметры/выходные параметры корневого уровня, и параметры также могут сослаться на запись double в массиве rtDataTypeMap. Это повторное использование информации уменьшает емкость памяти сгенерированного интерфейса.

Массивы структур, сгенерированные в файлах API C

Как с типом данных, интерфейс сопоставляет другую общую собственность (такую как адрес, размерность, масштабирование фиксированной точки и шаг расчета) в отдельные структуры и обеспечивает индекс в структуре для элемента данных. Для полного списка определений структуры отошлите к файлу matlabroot/rtw/c/src/rtw_capi.h. Этот файл также описывает каждого участника в структуре. Массивы структур, сгенерированные в model_capi.c (или .cpp) файл, имеют типы структуры, заданные в файле rtw_capi.h. Вот краткое описание массивов структур, сгенерированных в model_capi.c (или .cpp):

Сгенерируйте пример C файлы API

Подтемы C Сигналы API, C состояния API, C Вводы и выводы Корневого Уровня API и Параметры API C обсуждают сгенерированные структуры API C с помощью модели rtwdemo_capi в качестве примера. Чтобы сгенерировать код из модели в качестве примера, сделайте следующее:

Эта модель имеет три глобальных выходных сигнала блока, которые появятся в сгенерированном коде API C:

Модель также имеет два дискретных состояния, которые появятся в сгенерированном коде API C:

Модель имеет входные параметры/выходные параметры корневого уровня, которые появятся в сгенерированном коде API C, если вы выберете опцию Generate C API for: root-level I/O:

Кроме того, модель имеет пять глобальных параметров блоков, которые появятся в сгенерированном коде API C:

C сигналы API

Структура rtwCAPI_Signals получает информацию сигнала включая имя сигнала, адрес, блок path, номер выходного порта, информацию о типе данных, информацию о размерностях, информацию о фиксированной точке и информацию о шаге расчета.

Вот раздел кода в rtwdemo_capi_capi.c, который предоставляет информацию о сигналах API C для топ-модели в rtwdemo_capi:

/* Block output signal information */
static const rtwCAPI_Signals rtBlockSignals[] = {
  /* addrMapIndex, sysNum, blockPath,
   * signalName, portNumber, dataTypeIndex, dimIndex, fxpIndex, sTimeIndex
   */
  { 0, 0, "rtwdemo_capi/Gain1",
    "top_sig1", 0, 0, 0, 0, 0 },

  { 1, 0, "rtwdemo_capi/lu2d",
    "sig2_eg", 0, 0, 1, 0, 0 },

  {
    0, 0, (NULL), (NULL), 0, 0, 0, 0, 0
  }
};

  { 0, 0, "rtwdemo_capi/Gain1",
    "top_sig1", 0, 0, 0, 0, 0 },

Каждый элемент массива, кроме последнего, описывает один выходной порт для блока-сигнала. Итоговый элемент массива является сигнальной меткой с установленными в NULL значениями всех элементов. Например, исследуйте второй сигнал, описанный следующим кодом:

  { 1, 0, "rtwdemo_capi/lu2d",
    "sig2_eg", 0, 0, 1, 0, 0 },

Этот сигнал, названный sig2_eg, является выходным сигналом первого порта блока rtwdemo_capi/lu2d. (Этот порт является первым портом, потому что основанный на нуле индекс для portNumber, отображенного на второй строке, присвоен значение 0.)

Адрес этого сигнала дан addrMapIndex, который, в этом примере, отображен на первой строке как 1. Это обеспечивает индекс в массив rtDataAddrMap, найденный позже в rtwdemo_capi_capi.c:

/* Declare Data Addresses statically */
static void* rtDataAddrMap[] = {
  &rtwdemo_capi_B.top_sig1,            /* 0: Signal */
  &sig2_eg[0],                         /* 1: Signal */
  &rtwdemo_capi_DWork.top_state,       /* 2: Discrete State */
  &rtP_Ki,                             /* 3: Model Parameter */
  &rtP_Kp,                             /* 4: Model Parameter */
  &rtP_p1[0],                          /* 5: Model Parameter */
  &rtP_p2[0],                          /* 6: Model Parameter */
  &rtP_p3[0],                          /* 7: Model Parameter */
};

Индекс 1 указывает на второй элемент в массиве rtDataAddrMap. От массива rtDataAddrMap можно вывести, что адресом этого сигнала является &sig2_eg[0].

Этот уровень абстракции поддерживает несколько экземпляров кода той же модели. Для нескольких экземпляров информация сигнала остается постоянной, за исключением адреса. В этом случае модель является одним экземпляром. Поэтому rtDataAddrMap объявляется статически. Если вы принимаете решение сгенерировать повторно используемый код, инициализировать функция сгенерирована, который инициализирует адреса динамически на экземпляр. Для получения дополнительной информации при генерации повторно используемого кода, смотрите, Конфигурируют Генерацию кода для Образцовых Функций Точки входа (Simulink Coder) и видят, Конфигурируют Поддержку Повторного использования кода.

dataTypeIndex обеспечивает индекс в массив rtDataTypeMap, найденный позже в rtwdemo_capi_capi.c, указывая на тип данных сигнала:

/* Data Type Map - use dataTypeMapIndex to access this structure */
static const rtwCAPI_DataTypeMap rtDataTypeMap[] = {
  /* cName, mwName, numElements, elemMapIndex, dataSize, slDataId, *
   * isComplex, isPointer */
  { "double", "real_T", 0, 0, sizeof(real_T), SS_DOUBLE, 0, 0 }
};

Поскольку индексом является 0 для sig2_eg, индекс указывает на первый элемент структуры в массиве. Можно вывести, что типом данных сигнала является double. Значением isComplex является 0, указывая, что сигнал не является комплексным. Вместо того, чтобы предоставлять информацию о типе данных непосредственно в структуре rtwCAPI_Signals, уровень абстракции введен. Косвенность позволяет несколько сигналов, которые совместно используют совпадающий тип данных, чтобы указать на одну структуру карты, сохраняя память для каждого сигнала.

dimIndex (индекс размерностей) обеспечивает индекс в массив rtDimensionMap, найденный позже в rtwdemo_capi_capi.c, указывая на размерности сигнала. Поскольку этим индексом является 1 для sig2_eg, индекс указывает на второй элемент в массиве rtDimensionMap:

/* Dimension Map - use dimensionMapIndex to access elements of ths structure*/
static const rtwCAPI_DimensionMap rtDimensionMap[] = {
  /* dataOrientation, dimArrayIndex, numDims, vardimsIndex */
  { rtwCAPI_SCALAR, 0, 2, 0 },

  { rtwCAPI_VECTOR, 2, 2, 0 },
...
};

От этой структуры можно вывести, что это - нескалярный сигнал, имеющий размерность 2. Значение dimArrayIndex, 2, обеспечивает индекс в rtDimensionArray, найденный позже в rtwdemo_capi_capi.c:

/* Dimension Array- use dimArrayIndex to access elements of this array */
static const uint_T rtDimensionArray[] = {
  1,                                   /* 0 */
  1,                                   /* 1 */
  2,                                   /* 2 */
...
};

fxpIndex (индекс фиксированной точки) обеспечивает индекс в массив rtFixPtMap, найденный позже в rtwdemo_capi_capi.c, указывая на информацию о фиксированной точке о сигнале. Ваш код может использовать масштабирующуюся информацию, чтобы вычислить реальное значение сигнала, с помощью уравнения V=SQ+B, где V “реально” (то есть, основа 10), значение, S задано пользователями, наклон, Q является “квантованным значением фиксированной точки” или “сохраненным целым числом”, и B задан пользователями смещение. Для получения дополнительной информации смотрите Масштабирующийся (Fixed-Point Designer).

Поскольку этим индексом является 0 для sig2_eg, сигнал не имеет информации о фиксированной точке. Индекс карты фиксированной точки нулевых средних значений, что сигнал не имеет информации о фиксированной точке.

sTimeIndex (индекс шага расчета) предоставляет индекс массиву rtSampleTimeMap, найденному позже в rtwdemo_capi_capi.c, указывая на информацию о задаче о сигнале. Если вы регистрируете многоскоростные сигналы или условно выполняемые сигналы, информация о выборке может быть полезной.

C состояния API

Информация о состоянии получений структуры rtwCAPI_States включая имя состояния, адрес, блок path, вводит (непрерывный или дискретный), информация о типе данных, информация о размерностях, информация о фиксированной точке и информация о шаге расчета.

Вот раздел кода в rtwdemo_capi_capi.c, который предоставляет информацию о состояниях API C для топ-модели в rtwdemo_capi:

/* Block states information */
static const rtwCAPI_States rtBlockStates[] = {
  /* addrMapIndex, contStateStartIndex, blockPath,
   * stateName, pathAlias, dWorkIndex, dataTypeIndex, dimIndex,
   * fixPtIdx, sTimeIndex, isContinuous
   */
  { 2, -1, "rtwdemo_capi/Delay1",
    "top_state", "", 0, 0, 0, 0, 0, 0 },

  {
    0, -1, (NULL), (NULL), (NULL), 0, 0, 0, 0, 0, 0
  }
};

Каждый элемент массива, кроме последнего, описывает состояние в модели. Итоговый элемент массива является сигнальной меткой с установленными в NULL значениями всех элементов. В этом примере код API C для топ-модели отображает одно состояние:

  { 2, -1, "rtwdemo_capi/Delay1",
    "top_state", "", 0, 0, 0, 0, 0, 0 },

Это состояние, названное top_state, задано для блока rtwdemo_capi/Delay1. Значение isContinuous является нулем, указывая, что состояние дискретно, а не непрерывно. Другие поля соответствуют подобно названным эквивалентам сигнала, описанным в Сигналах API C, можно следующим образом:

C вводы и выводы Корневого Уровня API

Структура rtwCAPI_Signals получает информацию о вводе/выводе корневого уровня включая имя ввода/вывода, адрес, блок path, номер порта, информацию о типе данных, информацию о размерностях, информацию о фиксированной точке и информацию о шаге расчета. (Эта структура также используется для выходных сигналов блока, как ранее описано в Сигналах API C.)

Вот раздел кода в rtwdemo_capi_capi.c, который предоставляет информацию о входных параметрах/выходных параметрах корневого уровня API C для топ-модели в rtwdemo_capi:

/* Root Inputs information */
static const rtwCAPI_Signals rtRootInputs[] = {
  /* addrMapIndex, sysNum, blockPath,
   * signalName, portNumber, dataTypeIndex, dimIndex, fxpIndex, sTimeIndex
   */
  { 3, 0, "rtwdemo_capi/In1",
    "", 1, 0, 0, 0, 0 },

  { 4, 0, "rtwdemo_capi/In2",
    "", 2, 0, 0, 0, 0 },

  { 5, 0, "rtwdemo_capi/In3",
    "", 3, 0, 0, 0, 0 },

  { 6, 0, "rtwdemo_capi/In4",
    "", 4, 0, 0, 0, 0 },

  {
    0, 0, (NULL), (NULL), 0, 0, 0, 0, 0
  }
};

/* Root Outputs information */
static const rtwCAPI_Signals rtRootOutputs[] = {
  /* addrMapIndex, sysNum, blockPath,
   * signalName, portNumber, dataTypeIndex, dimIndex, fxpIndex, sTimeIndex
   */
  { 7, 0, "rtwdemo_capi/Out1",
    "", 1, 0, 0, 0, 0 },

  { 8, 0, "rtwdemo_capi/Out2",
    "", 2, 0, 0, 0, 0 },

  { 9, 0, "rtwdemo_capi/Out3",
    "", 3, 0, 0, 0, 0 },

  { 10, 0, "rtwdemo_capi/Out4",
    "", 4, 0, 0, 0, 0 },

  { 11, 0, "rtwdemo_capi/Out5",
    "sig2_eg", 5, 0, 1, 0, 0 },

  { 12, 0, "rtwdemo_capi/Out6",
    "", 6, 0, 1, 0, 0 },

  {
    0, 0, (NULL), (NULL), 0, 0, 0, 0, 0
  }
};

Для получения информации об интерпретации значений в структуре rtwCAPI_Signals смотрите предыдущий раздел C Сигналы API.

C параметры API

rtwCAPI_BlockParameters и структуры rtwCAPI_ModelParameters получают информацию о параметре включая название параметра, блок path (для параметров блоков), адрес, информация о типе данных, информация о размерностях и информация о фиксированной точке.

Массив rtModelParameters содержит записи для переменных рабочей области, на которые ссылаются как настраиваемые параметры блока Simulink или данные Stateflow осциллографа машины. Например, настраиваемые параметры включают объекты Simulink.Parameter, которые используют класс памяти кроме Auto. Программное обеспечение Simulink Coder присваивает свои элементы только NULL или нулевые значения в отсутствие таких данных.

Установка, что вы выбираете для образцового параметра конфигурации Default parameter behavior, определяет, как информация сгенерирована в массив rtBlockParameters в model_capi.c (или .cpp).

Последний член каждого массива является сигнальной меткой с установленными в NULL значениями всех элементов.

Вот массив rtBlockParameters, который сгенерирован по умолчанию в rtwdemo_capi_capi.c:

/* Individual block tuning is not valid when inline parameters is *
 * selected. An empty map is produced to provide a consistent     *
 * interface independent  of inlining parameters.                 *
 */
static const rtwCAPI_BlockParameters rtBlockParameters[] = {
  /* addrMapIndex, blockPath,
   * paramName, dataTypeIndex, dimIndex, fixPtIdx
   */
  {
    0, (NULL), (NULL), 0, 0, 0
  }
};

В этом примере, только финал, элемент массива сигнальной метки сгенерирован со всеми членами структуры набор rtwCAPI_BlockParameters к NULL и нулевым значениям. Это вызвано тем, что Default parameter behavior установлен в Inlined по умолчанию для модели rtwdemo_capi в качестве примера. Если вы устанавливаете Default parameter behavior на Tunable, параметры блоков сгенерированы в структуре rtwCAPI_BlockParameters. Однако переменные MATLAB и настраиваемые параметры появляются в структуре rtwCAPI_ModelParameters.

Вот массив rtModelParameters, который сгенерирован по умолчанию в rtwdemo_capi_capi.c:

/* Tunable variable parameters */
static const rtwCAPI_ModelParameters rtModelParameters[] = {
  /* addrMapIndex, varName, dataTypeIndex, dimIndex, fixPtIndex */
  { 2, TARGET_STRING("Ki"), 0, 0, 0 },

  { 3, TARGET_STRING("Kp"), 0, 0, 0 },

  { 4, TARGET_STRING("p1"), 0, 2, 0 },

  { 5, TARGET_STRING("p2"), 0, 3, 0 },

  { 6, TARGET_STRING("p3"), 0, 4, 0 },

  { 0, (NULL), 0, 0, 0 }
};

В этом примере массив rtModelParameters содержит записи для каждой переменной, на которую ссылаются как настраиваемый параметр блока Simulink.

Например, varName (имя переменной) четвертого параметра является p2. Другие поля соответствуют подобно названным эквивалентам сигнала, описанным в Сигналах API C, можно следующим образом:

Для получения дополнительной информации об устройстве хранения данных настраиваемого параметра в сгенерированном коде, смотрите Как Хранилища Сгенерированного кода Внутренний Сигнал, состояние и Данные о Параметре.

Карта C Структуры данных API к rtModel

Структура данных модели реального времени инкапсулирует данные модели и сопоставленную информацию, которая описывает модель полностью. Когда вы выбираете функцию API C и генерируете код, генератор кода Simulink Coder добавляет другого участника в структуру данных модели реального времени, сгенерированную в model.h:

/*
 * DataMapInfo:
 * The following substructure contains information regarding
 * structures generated in the model's C API.
 */
struct {
  rtwCAPI_ModelMappingInfo mmi;
} DataMapInfo;

Этот участник задает mmi (для модели, сопоставляющей информацию) типа struct rtwCAPI_ModelMappingInfo. Структура расположена в matlabroot/rtw/c/src/rtw_modelmap.h. Подструктура mmi задает интерфейс между моделью и файлами API C. А именно, члены mmi сопоставляют структуру данных модели реального времени со структурами в model_capi.c (или .cpp).

Инициализация значений участников mmi к массивам выполняет отображение, как показано в Модели Карты к Массивам API C Структур. Каждый участник указывает на один из массивов структур в сгенерированном файле API C. Например, адрес массива rtBlockSignals структур выделяется первому члену подструктуры mmi в model.c (или .cpp), с помощью следующего кода в файле rtw_modelmap.h:

/* signals */
struct {
    rtwCAPI_Signals const *signals;     /* Signals Array */
    uint_T                numSignals;   /* Num Signals   */
    rtwCAPI_Signals const *rootInputs;  /* Root Inputs array */
    uint_T               numRootInputs; /* Num Root Inputs  */
    rtwCAPI_Signals const *rootOutputs; /* Root Outputs array */
    uint_T               numRootOutputs;/* Num Root Outputs  */
} Signals;

Модель инициализирует функцию в model.c (или .cpp) выполняет инициализацию путем вызова API C, инициализируют функцию. Например, следующий код сгенерирован в модели, инициализируют функцию, например, модель rtwdemo_capi:

/* Initialize DataMapInfo substructure containing ModelMap for C API */
rtwdemo_capi_InitializeDataMapInfo(rtwdemo_capi_M);