C Function

Использование C кода в моделях.

c function

Описание

Блок C Function позволяет в моделях Engee использовать код на языке C и разделяемые библиотеки, имеющие C API.

При подключении динамической библиотеки, использующей внутренние статические переменные, стоит убедиться в том, что она предоставляет API для инициализации/деинициализации этих переменных. Соответствующие функции необходимо вызывать во вкладках StartCode и TerminateCode редактора исходного кода. В противном случае, статические переменные будут сохранять свои последние значения между симуляциями, что может приводить к неправильным результатам при повторных запусках модели.

Использование

Для интеграции исходного C кода в модель Engee необходимо:

Добавить в модель блок C Function из раздела Базовые/Пользовательские функции библиотеки блоков;
Нажать на кнопку Редактировать исходный код, после чего будет открыт редактор исходного кода.

c function settings

Редактор исходного кода

Рабочая область редактора исходного кода состоит из трех вкладок:

Output code содержит код, выполняющийся на каждом шаге расчета модели.
Start code содержит код, выполняющийся один раз при инициализации модели.
Terminate code содержит код, выполняющийся один раз при остановке модели.

c function code editor

В каждой из секций выполняется подсветка синтаксиса языка C.

Блок специальных комментариев

В секции Output code расположен блок специальных комментариев, имеющих значение для симулятора и генератора кода.

Комментарии позволяют связать переменные в исходном коде с сигналами (входами и выходами) блока C Function, а также указать дополнительную информацию, необходимую для сборки кода и его использования в модели.

Блок должен начинаться с комментария // engee-cfunction-start и заканчиваться комментарием // engee-cfunction-end.

Связывание переменных в исходном коде с сигналами блока C Function

Для связывания переменных (символов) исходного C кода со входами и выходами блока C Function, а также для определения их типов данных и размерности, используются специальные комментарии, начинающиеся с // symbol.

Токен Назначение

Токен	Назначение
`Name`	Определяет имя переменной в исходном C коде.
`Scope`	Определяет, чем является сигнал (входом или выходом блока C Function). Может принимать значения: `Input`, `Output`.
`Label`	Определяет имя порта в блоке C Function.
`Type`	Определяет тип данных переменной в исходном C коде. Должен совпадать с типом данных сигнала. Поддерживаются базовые типы данных языка Си: `int8_t`, `uint8_t`, `int16_t`, `uint16_t`, `int32_t`, `uint32_t`, `int64_t`, `uint64_t`, `float`, `double`
`Size`	Определяет размерность сигнала.
`Port`	Определяет номер порта в блоке C Function.

Name

Определяет имя переменной в исходном C коде.

Scope

Определяет, чем является сигнал (входом или выходом блока C Function).

Может принимать значения: Input, Output.

Label

Определяет имя порта в блоке C Function.

Type

Определяет тип данных переменной в исходном C коде.

Должен совпадать с типом данных сигнала.

Поддерживаются базовые типы данных языка Си:

int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, int64_t, uint64_t, float, double

Size

Определяет размерность сигнала.

Port

Определяет номер порта в блоке C Function.

Токены в строке // symbol могут разделяться любым количеством whitespace-символов (пробел, табуляция).

Описание специальных комментариев для сборки

Для того чтобы указать дополнительную информацию, необходимую для сборки кода и его использования в модели, используются специальные комментарии, начинающиеся с // build.

Комментарий Назначение Пример

Комментарий	Назначение	Пример
`// build source_files`	Используется для подключения дополнительных файлов исходного кода. Должен включать путь и имя файла вместе с расширением.	`// build source_files /user/project/src/example.c`
`// build include_directories`	Используется для определения пути к каталогу, содержащему заголовочные файлы.	`// build include_directories /user/project/include`
`// build library_directories`	Используется для определения пути к каталогу, содержащему разделяемые библиотеки.	`// build library_directories /user/project/third_party`
`// build headers`	Используется для подключения заголовочных файлов. Должен включать имя заголовочного файла вместе с расширением.	`// build headers example.h`
`// build defines`	Используется для определения дополнительных директив `#define`.	`// build defines LOWER=0 UPPER=300 STEP=20`
`// build libraries`	Используется для подключения библиотек. Должен включать имя библиотеки вместе с расширением.	`// build libraries libexample.so`

// build source_files

Используется для подключения дополнительных файлов исходного кода.

Должен включать путь и имя файла вместе с расширением.

// build source_files /user/project/src/example.c

// build include_directories

Используется для определения пути к каталогу, содержащему заголовочные файлы.

// build include_directories /user/project/include

// build library_directories

Используется для определения пути к каталогу, содержащему разделяемые библиотеки.

// build library_directories /user/project/third_party

// build headers

Используется для подключения заголовочных файлов.

Должен включать имя заголовочного файла вместе с расширением.

// build headers example.h

// build defines

Используется для определения дополнительных директив #define.

// build defines LOWER=0 UPPER=300 STEP=20

// build libraries

Используется для подключения библиотек.

Должен включать имя библиотеки вместе с расширением.

// build libraries libexample.so

Токены в строке // build могут разделяться любым количеством whitespace-символов (пробел, табуляция).

Особенности генерации С кода из блока C Function

Блок C Function поддерживает генерацию C кода.

При генерации кода блок C Function превращается в функции, оборачивающие содержимое секций Output code, Start code и Terminate code.

В данный момент генератор C кода не выдает дополнительную информацию для системы сборки, которая бы основывалась на директивах // build блока C Function. Поэтому пользователю необходимо правильно встроить сгенерированный код во внешнюю среду сборки с подключением зависимостей.

Порты

Вход

Port_1 — входной сигнал
скаляр | вектор

Входные порты автоматически добавляются в нужном количестве исходя из того, что указано в строках // symbol в блоке специальных комментариев.

Подробнее см. Связывание переменных с портами блока

Выход

Port_1 — выходной сигнал
скаляр | вектор

Выходные порты автоматически добавляются в нужном количестве исходя из того, что указано в строках // symbol в блоке специальных комментариев.

Подробнее см. Связывание переменных с портами блока

Параметры

Основные

Parameters — задает параметр как переменную
; (по умолчанию)

Parameters представляет собой именованный кортеж параметров, которые должны передаваться в качестве аргументов функциям step, init и terminate.

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

Parameters задает параметр как переменную. Заданные параметры становятся глобальными переменными, что позволит получить к ним доступ из любой секции:

Start code — код, выполняющийся при инициализации модели.
Output code — код, выполняющийся на каждом шаге расчета модели.
Terminate code — код, выполняющийся при завершении симуляции модели.

Параметры функции помечаются квалификатором const, что означает, что их значение не может быть изменено внутри кода функции. Если вы попытаетесь изменить значение такой переменной, это приведет к ошибке.

Если передается только один параметр, запятая перед закрывающей скобкой ) является обязательной.

Пример:

c function example 1

Sample time — интервал между шагами расчета
−1 (по умолчанию)

Укажите интервал между шагами расчета как неотрицательное число. Чтобы наследовать шаг расчета, установите для этого параметра значение −1.

Дополнительные возможности

Генерация Си кода: Да

Примеры

Интеграция C кода в модели Engee с использованием блока C Function