Files
Balsam_167/Doc/api.dox

724 lines
22 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
@file api.dox
@brief Русскоязычные Doxygen-описания интерфейсов Balsam 167.
@defgroup measurement Измерения и диагностика
@brief АЦП, фильтрация, пересчёт каналов и формирование аварий.
@{
*/
/**
@fn void setup_adc(void)
@brief Настраивает ADC и быстрый обработчик преобразований.
@details Конфигурирует последовательность каналов и параметры накопления,
используемые измерительным контуром. Вызывается один раз при старте для всех
ролей, кроме пульта EPLT.
*/
/**
@fn void adc_isr(void)
@brief Обрабатывает очередную последовательность преобразований ADC.
@details Обновляет сырые выборки и фильтры; выполняется в контексте прерывания.
*/
/**
@fn void Init_sensors(void)
@brief Выполняет первичную инициализацию измерительных каналов.
*/
/**
@fn void Init_sensors_more(void)
@brief Применяет параметры изделия после загрузки сохранённых настроек.
*/
/**
@fn void Init_packMask(void)
@brief Формирует маски публикуемых CAN-регистров для каждой шины.
*/
/**
@fn void Temper_count(int chan, int own)
@brief Пересчитывает температурный канал и обновляет его диагностику.
@param chan Индекс базового канала в общей модели измерений.
@param own Признак локального либо внешнего источника температуры.
*/
/**
@fn void Current_count(int chan)
@brief Вычисляет ток по паре измерительных каналов и формирует ошибки.
@param chan Индекс канала тока.
*/
/**
@fn void Power_count(int chan)
@brief Вычисляет напряжение/мощность для заданного канала.
@param chan Индекс обрабатываемого канала.
*/
/**
@fn void calc_sensor_koef(void)
@brief Пересчитывает коэффициенты датчиков по калибровочным точкам.
*/
/**
@fn void calc_volta_edge(void)
@brief Пересчитывает пороги контроля напряжения из текущих настроек.
*/
/**
@fn void Is_Voltage_Hi(void)
@brief Проверяет превышение напряжения и обновляет общий признак аварии.
*/
/**
@fn void cpu_timer1_isr_SENS(void)
@brief Периодический обработчик измерительной платы.
@details Планирует выбор каналов, пересчёт величин, диагностику, мигание и
циклическую передачу. Выполняется в контексте прерывания CPU Timer1.
*/
/**
@fn int er_anal(int term, unsigned int *count, long edge, int pre)
@brief Реализует выдержку времени для появления и снятия диагностического условия.
@param term Текущее логическое состояние диагностического условия.
@param count Счётчик длительности условия; изменяется функцией.
@param edge Порог счётчика, после которого условие подтверждается.
@param pre Состояние ошибки на предыдущем шаге.
@return Ненулевое значение, когда ошибка считается активной.
*/
/**
@struct FILTERBAT
@brief Состояние рекурсивного фильтра второго порядка.
@details Содержит три коэффициента, три входные и три выходные выборки.
*/
/**
@fn float filterbat(FILTERBAT *b, float InpVarCurr)
@brief Пропускает одну выборку через фильтр Баттерворта.
@param b Экземпляр фильтра с коэффициентами и историей.
@param InpVarCurr Новая входная выборка.
@return Отфильтрованное значение.
*/
/**
@struct ERROR
@brief Шестнадцатибитное слово состояния измерительного канала.
@details Объединяет признаки обрыва, неправильного сигнала, выхода за пределы,
перегрева, блокировки, готовности, дискретных входов, игнорирования и bypass.
*/
/**
@struct FLAG
@brief Общие признаки ошибки, аварии, нагрева и теста ламп.
*/
/**
@}
*/
/**
@defgroup communication Последовательный обмен и сообщения
@brief Два канала SCI, физический режим RS-485 и прикладные команды.
@{
*/
/**
@struct RS_DATA
@brief Контекст одного SCI/RS-485 канала.
@details Хранит регистры SCI, указатели RX/TX, буферы, длины сообщений,
тайм-ауты, адреса и параметры линии. Глобальные экземпляры: `rs_a` и `rs_b`.
*/
/**
@fn void create_uart_vars(char size_cmd15_set)
@brief Инициализирует контексты двух UART и таблицу длин команд.
@param size_cmd15_set Размер payload команды 15 для текущего приложения.
*/
/**
@fn void setup_uart(char commnumber, unsigned long speed_baud)
@brief Настраивает SCI-A или SCI-B и соответствующие обработчики PIE.
@param commnumber Номер порта: `COM_1` либо `COM_2`.
@param speed_baud Скорость линии, бит/с.
*/
/**
@fn void RS_SetLineMode(RS_DATA *rs_arr, int bit, char parity, int stop)
@brief Задаёт длину слова, чётность и число стоп-битов.
@param rs_arr Контекст канала.
@param bit Число информационных битов.
@param parity Режим контроля чётности.
@param stop Режим стоп-битов.
*/
/**
@fn void RS_SetLineSpeed(RS_DATA *rs_arr, unsigned long speed)
@brief Изменяет скорость выбранного последовательного канала.
@param rs_arr Контекст канала.
@param speed Новая скорость, бит/с.
*/
/**
@fn void RS_SetBitMode(RS_DATA *rs_arr, int n)
@brief Выбирает байтовый либо упакованный режим данных SCI.
@param rs_arr Контекст канала.
@param n Требуемый режим представления элементов.
*/
/**
@fn int RS_Send(RS_DATA *rs_arr, unsigned int *pBuf, unsigned long len)
@brief Запускает неблокирующую передачу массива слов.
@param rs_arr Контекст канала.
@param pBuf Буфер передаваемых слов.
@param len Число слов.
@return Признак успешного запуска передачи.
*/
/**
@fn int RS_BSend(RS_DATA *rs_arr, unsigned int *pBuf, unsigned long len)
@brief Запускает передачу байтов, хранящихся в 16-битных ячейках C28x.
@param rs_arr Контекст канала.
@param pBuf Буфер данных.
@param len Число восьмибитных элементов.
@return Признак успешного запуска передачи.
*/
/**
@fn int get_command(RS_DATA *rs_arr)
@brief Проверяет принятый кадр и извлекает код команды.
@param rs_arr Контекст канала с принятым пакетом.
@return Код команды либо `-1`, если полного корректного кадра нет.
*/
/**
@fn void RSA_RX_Handler(void)
@brief Обработчик приёма SCI-A, делегирующий работу общему RX-автомату.
*/
/**
@fn void RSA_TX_Handler(void)
@brief Обработчик передачи SCI-A.
*/
/**
@fn void RSB_RX_Handler(void)
@brief Обработчик приёма SCI-B, делегирующий работу общему RX-автомату.
*/
/**
@fn void RSB_TX_Handler(void)
@brief Обработчик передачи SCI-B.
*/
/**
@fn void clear_timer_rs_live(RS_DATA *rs_arr)
@brief Сбрасывает счётчик контроля активности последовательного канала.
@param rs_arr Контекст канала.
*/
/**
@fn void test_rs_live(RS_DATA *rs_arr)
@brief Проверяет тайм-аут активности последовательного канала.
@param rs_arr Контекст канала.
*/
/**
@fn void ReceiveCommandModbus3(RS_DATA *rs_arr)
@brief Обрабатывает Modbus function 3 — чтение регистров.
@param rs_arr Канал, на котором принята команда.
*/
/**
@fn void ReceiveCommandModbus6(RS_DATA *rs_arr)
@brief Обрабатывает Modbus function 6 — запись одного регистра.
@param rs_arr Канал, на котором принята команда.
*/
/**
@fn void SendCommandModbus4(RS_DATA *rs_arr)
@brief Формирует запрос function 4 к внешнему устройству OWEN.
@param rs_arr Канал связи с устройством.
*/
/**
@fn void ReceiveAnswerModbus4(RS_DATA *rs_arr)
@brief Разбирает ответ OWEN на запрос входных регистров.
@param rs_arr Канал, на котором принят ответ.
*/
/**
@struct CMD_TO_TMS
@brief Формат короткой команды контроллеру.
@details Содержит адрес, номер команды, восемь байтов данных, CRC и добавочный байт.
*/
/**
@}
*/
/**
@defgroup can_bus CAN
@brief Инициализация eCAN-A, приём команд и публикация регистров.
@{
*/
/**
@fn void InitCan(int Port, int DevNum)
@brief Настраивает CAN-контроллер и почтовые ящики.
@param Port Зарезервированный номер CAN-порта; текущая плата использует порт 0.
@param DevNum Адрес/режим устройства, участвующий в конфигурации идентификаторов.
*/
/**
@fn void CAN_send(int Port, int data[], int Addr)
@brief Передаёт группу из трёх регистров общей модели.
@param Port Номер CAN-порта.
@param data Начало массива регистров.
@param Addr Адрес первого публикуемого регистра.
*/
/**
@fn void CANa_handler(void)
@brief Обработчик приёма eCAN-A; переносит данные mailbox в прикладную модель.
*/
/**
@fn void CANa_reset_err(void)
@brief Обрабатывает состояние ошибки eCAN-A и восстанавливает обмен.
*/
/**
@}
*/
/**
@defgroup storage Параметры, EEPROM и журнал
@brief Долговременное хранение конфигурации и диагностических выборок.
@{
*/
/**
@struct SE2P_DATA
@brief Описание операции с последовательной EEPROM.
@details Содержит указатель данных, размер операции и адрес EEPROM.
*/
/**
@struct SPISE2P_DRV
@brief Состояние и виртуальные методы драйвера SPI EEPROM.
*/
/**
@fn void InitSeeprom(void)
@brief Настраивает SPI-A, GPIO chip-select и Timer2 для EEPROM.
*/
/**
@fn void Seeprom_write(unsigned int adres, unsigned int buf[], unsigned int size)
@brief Синхронно записывает блок 16-битных слов во внешнюю EEPROM.
@param adres Адрес слова в EEPROM.
@param buf Буфер исходных слов.
@param size Количество записываемых слов.
*/
/**
@fn void Seeprom_read(unsigned int adres, unsigned int buf[], unsigned int size)
@brief Синхронно читает блок 16-битных слов из внешней EEPROM.
@param adres Адрес слова в EEPROM.
@param buf Буфер результата.
@param size Количество читаемых слов.
*/
/**
@fn void Default_params(void)
@brief Загружает заводские уставки и калибровочные значения в RAM.
*/
/**
@fn void Load_params(void)
@brief Читает настройки из EEPROM и проверяет их целостность.
*/
/**
@fn void Save_params(void)
@brief Записывает текущие настройки и контрольную сумму в EEPROM.
*/
/**
@struct LOG
@brief Границы и текущий указатель циклического журнала во внешней памяти.
*/
/**
@fn void clear_mem(void)
@brief Инициализирует область журнала и очищает её рабочее состояние.
*/
/**
@}
*/
/**
@defgroup hardware Аппаратные интерфейсы
@brief GPIO, режим платы, ЦАП и последовательная индикация.
@{
*/
/**
@fn void get_Mode(void)
@brief Читает конфигурационные входы и определяет `Mode` и `Desk`.
*/
/**
@fn void get_Buttons(void)
@brief Опросивает дискретные входы и обновляет биты кнопок/команд.
*/
/**
@fn void setup_leds_line(void)
@brief Временно настраивает линии двух диагностических светодиодов.
*/
/**
@fn void unsetup_leds_line(void)
@brief Возвращает мультиплексируемые линии из режима стартовой индикации.
*/
/**
@fn void select_tpl_canal(int n_tpl)
@brief Выбирает один канал мультиплексора термопар.
@param n_tpl Номер канала термопары.
*/
/**
@fn void select_tpl_255(void)
@brief Переводит адресные линии мультиплексора в неактивное состояние.
*/
/**
@fn void Setup_DAC_time(void)
@brief Вычисляет временные параметры программного обслуживания ЦАП.
*/
/**
@fn void Init_DAC(void)
@brief Инициализирует GPIO последовательного интерфейса ЦАП.
*/
/**
@fn void Anal_output(long vrot, long maxx)
@brief Выдаёт нормированное значение на аналоговый выход.
@param vrot Требуемое значение.
@param maxx Верхняя граница шкалы входного значения.
*/
/**
@fn void Load_runner(void)
@brief Обновляет выход нагрузки и формирует старт/стоп импульсы.
*/
/**
@fn void kanal_Send(int adr, long dat, int dot)
@brief Передаёт число на внешний семисегментный индикатор.
@param adr Адрес индикаторного канала.
@param dat Отображаемое целое значение.
@param dot Позиция десятичной точки.
*/
/**
@fn void cpu_timer1_isr_PULT(void)
@brief Периодический обработчик пульта и внешней индикации.
*/
/**
@}
*/
/**
@defgroup boot_protocol BIOS-протокол
@brief Команды удалённого чтения, записи, запуска и прошивки контроллера.
@{
*/
/**
@fn void Answer(RS_DATA *rs_arr, int n)
@brief Формирует и отправляет ответ BIOS-протокола.
@param rs_arr Канал ответа.
@param n Число элементов данных ответа.
*/
/**
@fn void init(RS_DATA *rs_arr)
@brief Возвращает идентификацию работающего приложения.
@param rs_arr Канал запроса.
*/
/**
@fn void initload(RS_DATA *rs_arr)
@brief Инициализирует сеанс загрузки программы.
@param rs_arr Канал запроса.
*/
/**
@fn void load(RS_DATA *rs_arr)
@brief Принимает очередной блок загружаемой программы.
@param rs_arr Канал запроса.
*/
/**
@fn void run(RS_DATA *rs_arr)
@brief Завершает загрузку и передаёт управление программе.
@param rs_arr Канал запроса.
*/
/**
@fn void peek(RS_DATA *rs_arr)
@brief Читает участок адресного пространства контроллера.
@param rs_arr Канал запроса и ответа.
*/
/**
@fn void poke(RS_DATA *rs_arr)
@brief Записывает данные в адресное пространство контроллера.
@param rs_arr Канал запроса.
*/
/**
@fn void upload(RS_DATA *rs_arr)
@brief Передаёт блок памяти контроллера ведущему устройству.
@param rs_arr Канал запроса и ответа.
*/
/**
@fn void tflash(RS_DATA *rs_arr)
@brief Выполняет команду обслуживания Flash TMS320F28335.
@param rs_arr Канал запроса и ответа.
*/
/**
@fn void xflash(RS_DATA *rs_arr)
@brief Обрабатывает совместимую команду доступа к внешней Flash/памяти.
@param rs_arr Канал запроса и ответа.
*/
/**
@fn void extendbios(RS_DATA *rs_arr)
@brief Обрабатывает расширенную команду BIOS-протокола.
@param rs_arr Канал запроса и ответа.
*/
/**
@fn unsigned int read_memory(unsigned long addr)
@brief Читает 16-битное слово по физическому адресу.
@param addr Адрес в пространстве данных C28x.
@return Прочитанное слово.
*/
/**
@fn void write_memory(unsigned long addr, unsigned int data)
@brief Записывает 16-битное слово по физическому адресу.
@param addr Адрес в пространстве данных C28x.
@param data Записываемое слово.
*/
/**
@}
*/
/**
@defgroup utilities Служебные функции
@brief CRC, внешняя зона памяти и точные задержки.
@{
*/
/**
@fn unsigned int get_crc_ccitt(unsigned int crc, unsigned int *buf, unsigned long size)
@brief Вычисляет CRC-CCITT для массива восьмибитных значений в словах C28x.
@param crc Начальное значение CRC.
@param buf Буфер входных значений.
@param size Число элементов.
@return Итоговое значение CRC.
*/
/**
@fn unsigned int get_crc_16(unsigned int crc, unsigned int *buf, unsigned long size)
@brief Вычисляет основной вариант CRC-16 проекта.
@param crc Начальное значение CRC.
@param buf Буфер входных значений.
@param size Число элементов.
@return Итоговое значение CRC.
*/
/**
@fn unsigned int get_crc_16b(unsigned int crc, unsigned int *buf, unsigned long size)
@brief Вычисляет CRC-16 с альтернативным порядком байтов.
@param crc Начальное значение CRC.
@param buf Буфер входных значений.
@param size Число элементов.
@return Итоговое значение CRC.
*/
/**
@fn int get_crc16(unsigned int *buf, int size)
@brief Вычисляет контрольное слово пакета прикладного протокола.
@param buf Буфер пакета.
@param size Число обрабатываемых элементов.
@return Шестнадцатибитное контрольное значение.
*/
/**
@fn void init_zone7(void)
@brief Настраивает зону XINTF7 для внешней памяти и периферии.
*/
/**
@fn void pause_us(unsigned long t)
@brief Выполняет программную задержку.
@param t Длительность в микросекундах согласно частоте проекта.
*/
/**
@fn void set_cntrl_addr(int cntrl_addr, int cntrl_addr_for_all)
@brief Устанавливает индивидуальный и групповой адреса контроллера.
@param cntrl_addr Индивидуальный адрес устройства.
@param cntrl_addr_for_all Групповой широковещательный адрес.
*/
/**
@fn void SPISE2P_DRV_init(SPISE2P_DRV *eeprom)
@brief Инициализирует низкоуровневый автомат SPI EEPROM.
@param eeprom Экземпляр драйвера.
*/
/**
@fn void SPISE2P_DRV_tick(SPISE2P_DRV *eeprom)
@brief Выполняет один шаг неблокирующего автомата EEPROM.
@param eeprom Экземпляр драйвера.
*/
/**
@fn void SPISE2P_DRV_csset(void)
@brief Деактивирует линию chip-select EEPROM.
*/
/**
@fn void SPISE2P_DRV_csclr(void)
@brief Активирует линию chip-select EEPROM.
*/
/**
@fn unsigned int spiSe2pFree(SPISE2P_DRV *se2p)
@brief Проверяет готовность автомата EEPROM к новой операции.
@param se2p Экземпляр драйвера.
@return Ненулевое значение, когда драйвер свободен.
*/
/**
@fn void spiSe2pWrite(SPISE2P_DRV *se2p, SE2P_DATA *data)
@brief Передаёт автомату описание операции записи.
@param se2p Экземпляр драйвера.
@param data Описание адреса, буфера и длины.
*/
/**
@fn void spiSe2pRead(SPISE2P_DRV *se2p, SE2P_DATA *data)
@brief Передаёт автомату описание операции чтения.
@param se2p Экземпляр драйвера.
@param data Описание адреса, буфера и длины.
*/
/**
@}
*/