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

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

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

Из командной строки MATLAB^® можно использовать set_param функционируйте, чтобы выбрать или очистить параметры конфигурации модели C API. В командной строке 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 в следующих подтемах сгенерированы с C как выходной язык.

Эта модель имеет три глобальных выходных сигнала блока, которые появятся в сгенерированном коде 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 объявляется статически. Если вы принимаете решение сгенерировать повторно используемый код, инициализировать функция сгенерирована, который инициализирует адреса динамически на экземпляр. Для получения дополнительной информации при генерации повторно используемого кода, смотрите, Конфигурируют генерацию кода C для Функций Точки входа Модели и видят, Конфигурируют Поддержку Повторного использования кода.

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 добавляет другой член в структуру данных модели реального времени, сгенерированную в modelH:

/*
 * 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 подструктура в modelC (или .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;

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

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