From 49e4a8a7d6aafe8e7f97a7ee9602ccfab6c1932b Mon Sep 17 00:00:00 2001
From: Coal56AB <coal56ab@noreply.localhost>
Date: Sat, 18 Jan 2025 20:41:38 +0300
Subject: [PATCH] =?UTF-8?q?=D0=9E=D0=B1=D0=BD=D0=BE=D0=B2=D0=B8=D1=82?=
 =?UTF-8?q?=D1=8C=20README.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 186 +++++++++++++++++++++++++++---------------------------
 1 file changed, 93 insertions(+), 93 deletions(-)

diff --git a/README.md b/README.md
index 4e71ce6..b1134bb 100644
--- a/README.md
+++ b/README.md
@@ -1,126 +1,126 @@
 # MATLAB 23550
- **����������**
-- [����� ��������� ����������](#�����-���������-����������)
-- [�������� �������� ����������](#��������-��������-����������)
-	- [�������� ��](#��������-��)
-	- [�������� ���������](#��������-���������)
-	- [��� ������������](#���-������������) 
-	- [��������� ����](#���������-����)
-- [����������](#����������)
-	- [������������ ����](#������������-����)
-	- [��� �������������� ���](#���-��������������-���)
-	- [��� ��������� �������](#���-���������-�������)
-	- [������ ��� ������������](#������)
+ **СОДЕРЖАНИЕ**
+- [Общая структура симулятора](#общая-структура-симулятора)
+- [Описание стуктуры симулятора](#описание-стуктуры-симулятора)
+	- [Оболочка МК](#оболочка-мк)
+	- [Оболочка программы](#оболочка-программы)
+	- [Код пользователя](#код-пользователя) 
+	- [Симуляция плат](#симуляция-плат)
+- [Инструкция](#инструкция)
+	- [Портирование кода](#портирование-кода)
+	- [Как скомпилировать код](#как-скомпилировать-код)
+	- [Как запустить отладку](#как-запустить-отладку)
+	- [Ошибки при портировании](#ошибки)
 
-## ����� ��������� ����������
-��� ��� ���������� S-Function ����� � ����� ***Inu***. � ��� ����������:
-- **�������� �� ([����� � �����](#��������-��))**: ��� S-Function, ������� ��������� ��� ���������
-- **�������� ��������� ([_app_wrapper_](#��������-���������))**: ��������� ��������� � S-Function
-- **��������� �� ([_Src_](#���-������������))**: ��������� ��� ���������
-- **��������� ���� (beta) ([_xilinx_wrapper_](#���������-����))**: ���������� ������� ����� (���� ������ ���)
+## Общая структура симулятора
+Код для компиляции S-Function лежит в папке ***Inu***. В ней содержатся:
+- **Оболочка МК ([файлы в корне](#оболочка-мк))**: код S-Function, который запускает код программы
+- **Оболочка программы ([_app_wrapper_](#оболочка-программы))**: связывает программу и S-Function
+- **Программа МК ([_Src_](#код-пользователя))**: программа для симуляции
+- **Симуляция плат (beta) ([_xilinx_wrapper_](#симуляция-плат))**: моделирует внешние платы (пока только ШИМ)
 
-����� ��������� ��������� ����������. ���������� ��� ������������ ������� ���� � MATLAB ��������� [����](#����������)
+Далее приведена структура симулятора. Инструкция для портирования другого кода в MATLAB приведена [ниже](#инструкция)
 
-## �������� �������� ����������
-����� ����������� �������� ���� ������ ����������:
-- [�������� ��](#��������-��)
-- [�������� ���������](#��������-���������)
-- [��� ������������](#���-������������)
-- [��������� ���� (beta)](#���������-����)
+## Описание стуктуры симулятора
+Здесь содержиться описание трех блоков симулятора:
+- [Оболочка МК](#оболочка-мк)
+- [Оболочка программы](#оболочка-программы)
+- [Код пользователя](#код-пользователя)
+- [Симуляция плат (beta)](#симуляция-плат)
 
-### �������� ��
-� ���� ����� ����������� �������� (����. wrapper) ��� ������� � �������� ��������� ����������������� � MATLAB (������ ��, �� ������ TMS). �������� ������������ ����� S-Function - ���� � Simulink, ������� �������� �� ���������������� ����. ���������� ���������� � ������� MSVC-�����������. 
+### Оболочка МК
+В этой папке содержиться оболочка (англ. wrapper) для запуска и контроля симуляции микроконтроллеров в MATLAB (любого МК, не только TMS). Оболочка представляет собой S-Function - блок в Simulink, который работает по скомпилированому коду. Компиляция происходит с помощью MSVC-компилятора. 
 
-S-Function �������� ������ �������: �� ���� `n` ��� ��������� ���������������� ��� � ���� ���� ���� ��� �����������. ������ ����� ����������� ���������� ����, S-Function ��������� �� ��������� ��� `n+1`.
+S-Function работает особым образом: на шаге `n` она запускает скомпилированный код и ждет пока этот код выполниться. Только когда завершается выполнение кода, S-Function переходит на следующий шаг `n+1`.
 
-�� ��������� �� ��� ����������� ����, ������� ������� �� �����������. ������� ���� ��������� ������������ � ���������� ������ ���� � ���� S-Function:
-- ��� ��������� ��������� ��������� ����� ��� ��������� ��. ���� ����� ����������� � ������ �������� ���� ���������, ����������� �����-�� �����, � ����� ������������������. ��� ��������� ���� S-Function ����������� � ������� �� ��������� ���.
-- ���������� ������� ����� ��������� �� � ����� ���������. ��� ����� ������������ ������ ������ ��� while. ���� ������ ������ ������� while, ��������� ������� ��������� ���������. � ���� ��������� ���� ���������, ��� ����������� ����� `while()` ������������ � ����� ������� �� ����� ������� `main()` � ��������� ����.
+Но программа МК это бесконечный цикл, который никогда не завершается. Поэтому есть несколько особенностей в выполнении такого кода в виде S-Function:
+- Для симуляции создается отдельный поток для программы МК. Этот поток запускается в начале текущего шага симуляции, выполняется какое-то время, а потом приостанавливается. Это позволяет коду S-Function завершиться и перейти на следующий шаг.
+- Необходимо закрыть поток программы МК в конце симуляции. Для этого используется особый дефайн для while. Этот дефайн помимо условия while, проверяет условие окончания симуляции. И если симуляцию надо завершить, все бесконечные циклы `while()` пропускаются и поток доходит до конца функции `main()` и завершает себя.
 
-����� �������� �������� 4 �����:
-- ***mcu_wrapper.c***         &emsp;&emsp;&emsp;                                  - ���, ������� ��������� ��� �� � ���������� ���������. � ��� ����������� ������� ��� �������/��������� ������ ��������� ��, ���������� ������ � ������ ������ S-Function.
-- ***MCU.c***                 &nbsp;&ensp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;    - ��� ��� ���������� S-Function � MATLAB. �������� ������� �� ***mcu_wrapper.c***
-- ***mcu_wrapper_conf.h***    &ensp;                                              - ����� ��� ***mcu_wrapper.c*** � ***MCU.c*** ������������ ����. �������� ��������� ��� ����� S-Function, � ����� ������� ��� ���������� ������� ��������� ��. 
-- ***run_mex.bat***           &nbsp;&emsp;&emsp;&emsp;&emsp;                      - ������ ��� ���������� ���� ������������ MSVC. � ��� ������������� ���� ��� ������������ ������ ***.h***, ����������� ����� ��������� ���� ***.c*** � ������������� ������� ��� ����������.
+Всего оболочка содержит 4 файла:
+- ***mcu_wrapper.c***         &emsp;&emsp;&emsp;                                  - код, который запускает код МК и симулирует периферию. В нем содержаться функции для запуска/остановки потока программы МК, считывании входов и запись входов S-Function.
+- ***MCU.c***                 &nbsp;&ensp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;    - код для компиляции S-Function в MATLAB. Вызывает функции из ***mcu_wrapper.c***
+- ***mcu_wrapper_conf.h***    &ensp;                                              - общий для ***mcu_wrapper.c*** и ***MCU.c*** заголовочный файл. Содержит настройки для блока S-Function, а также дефайны для управления потоком программы МК. 
+- ***run_mex.bat***           &nbsp;&emsp;&emsp;&emsp;&emsp;                      - скрипт для компиляции кода компилятором MSVC. В нем прописываются пути для заголовочных файлов ***.h***, указываются файлы исходного кода ***.c*** и прописываются дефайны для компиляции.
 
-������������ ��������:
-- `RUN_APP_MAIN_FUNC_THREAD` - �������� � ������ ���������� ������ ��� main()
-- `DEKSTOP_CYCLES_FOR_MCU_APP` - ���������� ������ ������� for(;;), � ������� �������� ����� �������� ����� main()
-- `MCU_CORE_CLOCK` - ������� ������������� ���������� (���� ����� �� ������������)
-- `IN_PORT_WIDTH` - ����������� �������� ������� S-Function
-- `IN_PORT_NUMB` - ���������� ������� �������� S-Function
-- `OUT_PORT_WIDTH` - ����������� ��������� ������� S-Function
-- `OUT_PORT_NUMB` - ���������� �������� �������� S-Function
+Конфигурации оболочки:
+- `RUN_APP_MAIN_FUNC_THREAD` - создание и запуск отдельного потока для main()
+- `DEKSTOP_CYCLES_FOR_MCU_APP` - количество циклов пустого for(;;), в течении которого будет работать поток main()
+- `MCU_CORE_CLOCK` - частота симулируемого процессора (пока нигде не используется)
+- `IN_PORT_WIDTH` - размерность входного вектора S-Function
+- `IN_PORT_NUMB` - количество входных векторов S-Function
+- `OUT_PORT_WIDTH` - размерность выходного вектора S-Function
+- `OUT_PORT_NUMB` - количество выходных векторов S-Function
 
-_Note: ������ `RUN_APP_MAIN_FUNC_THREAD` ���� �������� � ����� ��� main() �� ������������)_
+_Note: дефайн `RUN_APP_MAIN_FUNC_THREAD` пока выключен и поток для main() не используется)_
 
-_Note for future: ������ ������� ����� ������������ ��� ������ ����_
+_Note for future: разные вектора можно использовать для разных плат_
 
-### �������� ���������
-�������� ��� ��������� ��������� ����������� �������� �������� ���������. ��� �������������� ��, ��������� ����������� ��� �� ������ ������� � ��������� �� � �������/�������� S-Function
+### Оболочка программы
+Оболочка для программы позволяет имитировать реальный алгоритм программы. Она инициализирует её, запускает необходимые для её работы функции и связывает её с входами/выходами S-Function
 
-���� �������� �������� ���� ������ � ������� �������� ����� ��� �����:
-- ***app_includes.h***      &emsp;&emsp;&emsp;                                  - �������� ARM ������� ��� ���������� � MSVC.
-- ***app_init.c/.h***       &emsp;&emsp;&emsp;&emsp;                            - ������������� ���������
-- ***app_io.c/.h***         &nbsp;&ensp;&emsp;&emsp;&emsp;&emsp;                - ������/���������� ������/������� S-Function � ���������
-- ***app_wrapper.c/.h***    &nbsp;&nbsp;&ensp;&emsp;                            - ����� ������� �� ��������� � �������� �������� ��� �������� �������
-- ***def.h***               &ensp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;    - ������� ��� ��������� ��������� � ��������� (�������� �� ������������)
+Ниже приведен перечень всех файлов и краткое описание зачем они нужны:
+- ***app_includes.h***      &emsp;&emsp;&emsp;                                  - Содержит ARM дефайны для компиляции в MSVC.
+- ***app_init.c/.h***       &emsp;&emsp;&emsp;&emsp;                            - инициализация программы
+- ***app_io.c/.h***         &nbsp;&ensp;&emsp;&emsp;&emsp;&emsp;                - запись/считывание входов/выходов S-Function в программу
+- ***app_wrapper.c/.h***    &nbsp;&nbsp;&ensp;&emsp;                            - вызов функций из программы и создание заглушек для ненужных функций
+- ***def.h***               &ensp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;    - дефайны для симуляции программы в симулинке (осталось от улитковского)
 
-����� � ����� ***\app_wrapper\device_support*** ���������� ����������� ���������� ��� TMS, �� ������������ ��� ���������� MSVC (������ `volatile`, ��������� �������� ��� `interrupt`, `asm`, `cregister`, �������� ��� ��� ��������� IQlib).
+Также в папке ***\app_wrapper\device_support*** находяться стандартные библиотеки для TMS, но переделанные под компилятор MSVC (удален `volatile`, добавлены заглушки для `interrupt`, `asm`, `cregister`, добавлен код для симуляции IQlib).
 
-### ��� ������������
-������ ����� �������� �������� ��� ���������� ��. ��� ���� ����������� ����������, ������� ����� ��� ���� �������� ������� �������� � [����� � ��������� ���������](#��������-���������). ����� �� ������������� ��������� ����� ��������� � ������ �������.
+### Код пользователя
+Данная папка содержит исходный код приложения МК. При этом стандартные библиотеки, которые общие для всех проектов следует помещать в [папку с оболочкой программы](#оболочка-программы). Чтобы не редактировать исходники общих библиотек в каждом проекте.
 
-### ��������� ����
-������ � ���� ����� ���������� ������� �����. ���� �����-����� ������ ������ ���, �� � ������� ����������� ���������� � ����� �� � �������� S-Function. ����� ������� ������� �������. 
+### Симуляция плат
+Модули в этой папке моделируют внешние платы. Пока более-менее сделан только ШИМ, но в будущем планируется расширение и вывод их в отельные S-Function. Чтобы сделать подобие корзины. 
 
 ###### adc_sim
-***adc_sim.c/.h*** - ��������� ��� (���� ������ ���������)
+***adc_sim.c/.h*** - симуляция АЦП (пока просто заготовка)
 
 ###### pwm_sim
-***pwm_sim.c/.h*** - ��������� ���
-������������ ��� ������ ������������ ���:
-- ��� ������� ������� �������� (PWM_SIMULATION_MODE_REGULAR_PWM)
-- ����� ����� �� ��� ���� ���� ����� (PWM_SIMULATION_MODE_TK_LINES).
+***pwm_sim.c/.h*** - симуляция ШИМ
+Поддерживает два режимы формирования ШИМ:
+- для каждого таймера отдельно (PWM_SIMULATION_MODE_REGULAR_PWM)
+- через линии ТК для всей фазы разом (PWM_SIMULATION_MODE_TK_LINES).
 
 
-## ����������
-����� �������� ������������ ���� ��� ��������� � MATLAB �������� ����. � ���������� ���� ������ �� ����� ��������� �������� ��������.
-1. [����������� ��� ��� MATLAB](#������������-����) (����� ������ � ������������ ��� ��������� � ����� ����������� �� ���� 2)
-2. ��������� [�������������� �� ���](#���-��������������-���). � �����:
-    - ���� ���� ������ ��� ����������, [��������� ��](#������-���-����������) � ��������� �� ��� 2.
-    - ���� ������ ���, ������� �� ��� 3.
-3. ��������� ��������� �� ����������� � �������� ��������� � ��. � �����:
-    - ���� ��������� ��������, �� ���������� [��������� ������](#������-���-���������) � [������ �������](#���-���������-�������) � ��������� �� ��� 3.
-    - ���� ��������� ��������� ����������� ������ ���� ���, � �� ����������� ��� �� ����������� ������ ���, �� ���������� [��������� ������](#������-���-���������) � [������ �������](#���-���������-�������) � ��������� �� ��� 3.
-    - ���� ��������� ��������, �� �������� � ���������������, �� ������� �� ��� 4.
-4. ������� ���������� ���������. � �����:
-    - ���� ��������� �������� � ����������� - �� ��� �������� ���������. 
-    - ���� ��� - ���������� ����������� � ��������� � ����� ��������� ��� � ������� �� ��� 2.
+## Инструкция
+Общий алгоритм портирования кода для симуляции в MATLAB приведен ниже. В инструкции есть ссылки на более подробное описание действий.
+1. [Портировать код для MATLAB](#портирование-кода) (можно начать с портирования без изменений и далее действовать от шага 2)
+2. Проверить [компилируеться ли код](#как-скомпилировать-код). А далее:
+    - если есть ошибки при компиляции, [исправить их](#ошибки-при-компиляции) и вернуться на шаг 2.
+    - если ошибок нет, перейти на шаг 3.
+3. Проверить нормально ли запускается и работает симуляция с МК. А далее:
+    - если симуляции вылетает, то необходимо [исправить ошибки](#ошибки-при-симуляции) в [режиме отладки](#как-запустить-отладку) и вернуться на шаг 3.
+    - если симуляция нормально запускается только один раз, и не завершается или не запускается второй раз, то необходимо [исправить ошибки](#ошибки-при-симуляции) в [режиме отладки](#как-запустить-отладку) и вернуться на шаг 3.
+    - если симуляция работает, не вылетает и перезапускается, то перейти на шаг 4.
+4. Оценить результаты симуляции. А далее:
+    - если симуляция сходится с реальностью - то всё работает корректно. 
+    - если нет - необходимо разбираться в алгоритме и после исправить его и перейти на шаг 2.
 
-#### ������������ ����
-��� ������ ���������� ���� ���������������� ��� ����������� � ��������� ����� ��� ��������. �������� � "***\Src***".
+#### Портирование кода
+Для начала необходимо весь пользовательский код портировать в отдельную папку для удобства. Например в "***\Src***".
 
-����� � "[run_bat.mex](#��������-��)" ���� ��������� ���� ��� ������������ ������ (***\Includes***) � ��� ����������� ��� ��������� ��������� ���������. ��� ����� ���������� "***.c***" ����������� �� �����������. ���� ����� �������� �����-�� ��������� ������ ���������, ����� ����������� ������������ ��, � ��� ������������� ������ ���������� ����� ���������.
+Далее в "[run_bat.mex](#оболочка-мк)" надо прописать пути для заголовочных файлов (***\Includes***) и все необходимые для симуляции программы исходники. Все файлы исходников "***.c***" прописывать не обязательно. Если нужно отладить какой-то отдельный модуль программы, можно попробовать ограничиться им, и при возникновении ошибок подключать новые исходники.
 
-#### ��� �������������� ���
-��� ���������� ���� ���������� ������� ���� ***mexing.m***. ��� MATLAB-������, ������� ��������� ������ "[***run_bat.mex***](#��������-��)" ��� ����������. ���� ����������� ���������� ���� ��� [�������](#���-���������-�������)
+#### Как скомпилировать код
+Для компиляции кода необходимо открыть файл ***mexing.m***. Это MATLAB-скрипт, который запускает скрипт "[***run_bat.mex***](#оболочка-мк)" для компиляции. Есть возможность компиляции кода для [отладки](#как-запустить-отладку)
 
-#### ��� ��������� �������
-��� ������� ��������� ���������� ��������� � ***mexing.m*** � ������ ***run_mex.bat*** ����� `debug`, ����� ��� �������������� ��� ������. ����� ����� ���������� ������� Visual Studio, ������� ����� ������� (��� ������ ���� ��� ��������� ��������� � ����������). � ������������ � ***MATLAB.exe***.
+#### Как запустить отладку
+Для отладки симуляции необходимо приписать в ***mexing.m*** в вызове ***run_mex.bat*** слово `debug`, тогда код скомпилируется для дебага. После этого необходимо открыть Visual Studio, открыть папку проекта (там должны быть все исходники программы и симулятора). И подключиться к ***MATLAB.exe***.
 
-������ ����� ��������� ����� � �������� ���� ���������� ��� ��������� �� � ��������� ���������. ����� MATLAB ������ �� ����� �����, ��������� ������������ � � Visual Studio ����� ����� ���������� ��� ����������, ������ ��� �� ������� � � ����� ������ ��� ��, ��� ����� ������ � ������ �������.
+Теперь можно поставить точку в исходном коде симулятора или программы МК и запустить симуляцию. Когда MATLAB дойдет до этого места, симуляция остановиться и в Visual Studio можно будет посмотреть все переменные, пройти код по строкам и в общем делать всё то, что можно делать в режиме отладки.
 
-��� ������� ���������� ������� ����������� � ��������, � ����� ��� ��������� ���������. ����� ������� �������� ������ ���� ���. ��� ��������� ������� ��������� ��������� �� ����������. ������� ����� ������ �������� ���� ����������������� ���.
+Для отладки необходимо сначала подключится к процессу, а потом уже запускать симуляцию. Также отладка рабоатет только один раз. При повторном запуске симуляции остановки не произойдет. Поэтому перед каждой отладкой надо перекомпилировать код.
 
 
-#### ������
-##### ������ ��� ����������
-����� ��������������� ������ ����������� ��� ������������ ������ ���� - ��� ������ ��-�� �������������� �������� ������. ��� ����������� ������ ���������� ���������� ��������� ������ ��� ��������� ��������.
+#### Ошибки
+##### Ошибки при компиляции
+Самые распространеные ошибки компилятора при портировании нового кода - это ошибки из-за неподключенных исходных файлов. Для исправления ошибок необходимо подключить требуемые модули или создавать заглушки.
 
-����� ��� ����� ���� ������ ��������� � ������� ������������� � ���������� �������� ���� � MSVC, ��������, ������ � `volatile`, `interrupt`, `asm`... � ����������� DPS. ��� ����������� ������ ���� ��� ������� ��� �������� ����� ��� ��������� ��� ��� ��������-define
+Также еще могут быть ошибки связанные с разными компиляторами и отсутствия ключевых слов в MSVC, например, ошибки с `volatile`, `interrupt`, `asm`... в библиотеках DPS. Для исправления ошибок надо или удалять эти ключевые слова или создавать для них заглушки-define
 
-##### ������ ��� ���������
-������ ��� ���������� ��� ������ �� ������������ ������. ���� �������� �� ����� ������ ��������� ���������� � �������� �� ������ ������ ��������� ������� ������ � �� ������ ������ ���� �� ����� ���� ���������. � ����� ����� ��������������� ��� ���, ����� ����� ������ ����������.
+##### Ошибки при симуляции
+Обычно это исключения при чтении по недоступному адресу. Надо выяснить на какой строке произошло исключение и смотреть по какому адресу произошла попытка чтения и по какому адресу надо на самом деле считывать. И после этого скорректировать код так, чтобы адрес брался корректный.
 
-��� ������ �������������������� ��������� ��� ��������� ������� (����. `ReadMemory`/`WriteMemory` ����� �������� ������� ���-�� �� �������� "��������������" ����)
\ No newline at end of file
+Это обычно неинициализированные указатели или некоторые функции (напр. `ReadMemory`/`WriteMemory` когда пытаются считать что-то по адрессам "несуществующей" шины)
\ No newline at end of file