Обновление документации

README.md

@@ -1,2 +1,25 @@
 # RISCify
-Riscify - A web-based RISC-V disassembler that helps developers analyze and understand RISC-V instructions. Enter your byte stream and get the disassembled instructions in an easy-to-read format. Perfect for learning and experimenting with RISC-V assembly!
+
+RISC-V дизассемблер, работающий полностью в вашем браузере
+
+👉 [rudolf101.github.io/RISCify](https://rudolf101.github.io/RISCify/)
+
+Поддерживаются инструкции из расширений:
+- `I`
+- `M`
+- `A`
+- `F`
+- `D`
+- `Q`
+- `Zfh`
+- `Zawrs`
+- `Zicsr`
+- `Zifencei`
+- `C`
+- `B`
+
+[📘 Руководство пользователя](./doc/README.md)
+
+[🏗️ Сборка и локальный запуск](./app/README.md)
+
+[🧩 Добавление новых расширений](./dsl/README.md)

app/README.md

@@ -1,46 +1,54 @@
-# Getting Started with Create React App
+## 🏗️ Сборка
 
-This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
+```bash
+git clone https://github.com/rudolf101/RISCify.git && cd RISCify/app
+npm i
+npm run build
+```
 
-## Available Scripts
+## 🚀 Запуск
 
-In the project directory, you can run:
+### Локально
+```bash
+npm run build
+```
 
-### `yarn start`
+### На своём сервере
 
-Runs the app in the development mode.\
-Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
+```bash
+PUBLIC_URL=https://your.server.com/path/ npm run build
+```
 
-The page will reload if you make edits.\
-You will also see any lint errors in the console.
+После чего скопируйте файлы из папки `app/build` на сервер
 
-### `yarn test`
+### GitHub Pages
 
-Launches the test runner in the interactive watch mode.\
-See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
+Смотрите в файл [`.github/workflows/deploy.yml`](https://github.com/rudolf101/RISCify/blob/main/.github/workflows/deploy.yml). При необходимости замените `DEPLOY_TOKEN` на `GITHUB_TOKEN`
 
-### `yarn build`
+## 🧩 Добавление новых инструкций
 
-Builds the app for production to the `build` folder.\
-It correctly bundles React in production mode and optimizes the build for the best performance.
+[Подробная документация по DSL для инструкций](https://github.com/rudolf101/RISCify/blob/main/dsl/README.md)
 
-The build is minified and the filenames include the hashes.\
-Your app is ready to be deployed!
+После редактирования `.yml`-файлов запустите в корне проекта
 
-See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
+```bash
+npx tsx app/src/generator/run.ts
+```
 
-### `yarn eject`
+После чего вы должны увидеть новые инструкции в файле `app/src/kernel/Description.generated.ts`
 
-**Note: this is a one-way operation. Once you `eject`, you can’t go back!**
+## 🧪 Тестирование и разработка
 
-If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.
+Запуск тестов:
 
-Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.
+```bash
+npm test
+```
 
-You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.
+Запуск линтера:
 
-## Learn More
+```bash
+npm run lint
+```
 
-You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
-
-To learn React, check out the [React documentation](https://reactjs.org/).
+Тесты автоматически запускаются при коммитах в любую из веток. Также есть проверки `.yml`-описаний, актуальности автогенерируемого кода и собираемости проекта. Они описаны в файле [`.github/workflows/tests.yml`](https://github.com/rudolf101/RISCify/blob/main/.github/workflows/tests.yml)

app/src/README.md

@@ -1,54 +1,52 @@
 # SRC
 
-В настоящее время Проект переписывается на
-болле сопровождаемую кодовую базу.
-
-Актуальные каталоки и файлы:
+Содержимое:
+- [`generator`](./generator/)
+  - Генератор кода.
 - [`kernel`](./kernel/)
-  - Ядро дизассемлера
+  - Ядро дизассемлера.
+  - [`Adjuster.ts`](./kernel/Adjuster.ts)
+    - Обработчик адресов переходов. Переводит смещениия в байтах в смещения в инструкциях.
   - [`Argument.ts`](./kernel/Argument.ts)
-    - Уже готовый аргумент инструкции на выходе из дизассемблера
+    - Уже готовый аргумент инструкции на выходе из дизассемблера.
   - [`ArgumentInterpretation.ts`](./kernel/ArgumentInterpretation.ts)
-    - Описание того, как интерпретировать аргумент,
-      переданный в виде битов
+    - Описание того, как интерпретировать аргумент, переданный в виде битов.
   - [`ArgumentPattern.ts`](./kernel/ArgumentPattern.ts)
-    - Описание того, как из инструкции выделить аргумент,
-      и как его интерпретировать
+    - Описание того, как из инструкции выделить аргумент, и как его интерпретировать.
   - [`Bits.ts`](./kernel/Bits.ts)
-    - Последовательность бит в LITTLE-ENDIAN
-  - [`Descriptions.ts`](./kernel/Descriptions.ts)
-    - Список описаний инструкций
-    - Этот файл должен генерироваться из YAML-описаний
-      во время развёртывания 
+    - Последовательность бит.
+  - [`Descriptions.generated.ts`](./kernel/Descriptions.generated.ts)
+    - Список описаний инструкций;
+    - Этот файл должен генерироваться из YAML-описаний.
   - [`Disassembler.ts`](./kernel/Disassembler.ts)
-    - Дизассемблер
+    - Основная функция дизассемблера.
   - [`InputParser.ts`](./kernel/InputParser.ts)
-    - Преобразует пользовательский ввод в последовательность бит
+    - Преобразует пользовательский ввод в последовательность бит.
   - [`Instruction.ts`](./kernel/Instruction.ts)
-    - Результат дизассемблирования одной инструкции
+    - Результат дизассемблирования одной инструкции.
   - [`InstructionDescription.ts`](./kernel/InstructionDescription.ts)
-    - Описание инструкции
+    - Описание инструкции.
+  - [`Kernel.ts`](./kernel/Kernel.ts)
+    - Фасадная функция всего дизассемблера.
   - [`Matcher.ts`](./kernel/Matcher.ts)
-    - Сопоставитель для определения полей и ограничителей
+    - Сопоставитель для определения полей и ограничителей.
   - [`Span.ts`](./kernel/Span.ts)
-    - Описывает выборку и перестановку битов, тобы преобразовать
-      одну последовательность бит в другую
+    - Описывает выборку и перестановку битов, тобы преобразовать одну последовательность бит в другую.
   - [`Splitter.ts`](./kernel/Splitter.ts)
-    - разделяет сплошную последовательность бит на чанки,
-      каждый из которых соответствует одной инструкции
+    - Разделяет сплошную последовательность бит на чанки, каждый из которых соответствует одной инструкции.
 - [`ui`](./ui/)
   - Пользовательский интерфейс
+  - [`About.tsx`](./ui/About.tsx)
+    - Окошко с информацией.
   - [`App.tsx`](./ui/App.tsx)
-    - Вся страница
-  - [`AssemblyTable.tsx`](./ui/AssemblyTable.tsx)
-    - Интерактивная таблица с результатом дизассемблирования
-  - [`InputField.tsx`](./ui/InputField.tsx)
-    - Поле ввода дампа памяти
-  - [`InstructionBox.tsx`](./ui/InstructionBox.tsx)
-    - Элеиент, отображающий одну инструкцию
-  - [`InstructionRow.tsx`](./ui/InstructionRow.tsx)
-    - Строка таблицы
-  - [`SettingsBox.tsx`](./ui/SettingsBox.tsx)
-    - Панель настроек
-
-Когда будут готовы модули будем собирать и удалять старый код.
+    - Вся страница.
+  - [`Arrows.tsx`](./ui/Arrows.tsx)
+    - Поле для стрелочек.
+  - [`Code.tsx`](./ui/Code.tsx)
+    - Поле для дизассемблированного кода.
+  - [`Message.tsx`](./ui/Message.tsx)
+    - Поле для вывода ошибки.
+  - [`Switch.tsx`](./ui/Switch.tsx)
+    - Элемент ПИ: переключатель.
+- [`index.tsx`](./index.tsx)
+  - Точка входа.

app/src/ui/App.tsx

@@ -155,7 +155,7 @@ const App = () => {
         {aboutOpened ? (
           <About />
         ) : sourceCode.length === 0 ? (
-          <Message header="PASTE CODE" text="CTRL + V" />
+          <Message header="PASTE HEX DUMP" text="CTRL + V" />
         ) : disassemblerResult.valid === "invalid" ? (
           <Message
             header="FAILED TO DECODE"

doc/README.md

@@ -4,26 +4,19 @@
 
 ![Изображение интерфейса](images/interface.png)
 
-1. Поле ввода двоичного кода в шестнадцатеричном виде.
-   Подробнее см. таблицу ниже. 
-2. Кнопка для запуска дизассемблера.
-3. Список дизассемблированных инструкций.
-4. Представление инструкции в ассемблерном виде.
-5. У одного битового представления может быть несколько 
-   интерпретаций.
-6. Развёрнутое представление инструкции. Появляется и
-   скрывается по щелчку левой кнопки мыши по инструкции.
-7. Двоичное представление полей инструкции.
-8. Аргументы инструкции.
-
-Формат ввода на примере `37 03 4000 00000293`:
-```
-Input:          37   03   0040      00000293
-Bytes:         [37] [03] [40   00] [93   02   00   00]
-Grouped bytes: [37   03   40   00] [93   02   00   00]
-Instructions:   00400337             00000293
-ASM:            lui x6 1024         mv x5 x0
-```
+1. Панель управления
+2. Переключение разрядности архитектуры
+3. Пропуск первых байтов из дампа на случай, если дамп начинается с обрывка инструкции
+4. Порядок байт как для вывода представления инструкций в дампе, так и для парсинга дампа, когда несколько байт идут подряд без пробелов
+5. Переключение между HEX/BIN представлением (в бинарном при ховере по аргументам подсвечиваются их биты)
+6. Относительные/Абсолютные смещения у инструкций потока управления
+7. Вызов панели редактирования дампа
+8. Показ информации
+9. Дизассемблированный код
+10. Адреса инструкций
+11. Представление инструкций в дампе
+12. Мнемоники инструкций с аргументами
+13. Панель редактирования дампа (скрываемая)
 
 ## Поддерживаемые расширения
 
@@ -39,3 +32,46 @@ ASM:            lui x6 1024         mv x5 x0
     - `Zawrs`
     - `Ziscr`
     - `Zifencei`
+  - `C`
+  - `B`
+
+## Пример дампа
+
+```
+13 01 01 fe
+23 2e 11 00
+23 2c 81 00
+13 04 01 02
+23 26 a4 fe
+23 24 b4 fe
+83 27 84 fe
+87 a7 07 00
+53 07 00 f0
+d3 a7 e7 a0
+63 86 07 02
+83 27 84 fe
+93 87 47 00
+87 a7 07 00
+53 07 00 f0
+d3 a7 e7 a0
+63 86 07 00
+93 07 f0 ff
+6f 00 40 03
+93 07 00 00
+6f 00 c0 02
+83 27 84 fe
+93 87 47 00
+87 a7 07 00
+53 97 f7 20
+83 27 84 fe
+87 a7 07 00
+d3 77 f7 18
+83 27 c4 fe
+27 a0 f7 00
+93 07 10 00
+13 85 07 00
+83 20 c1 01
+03 24 81 01
+13 01 01 02
+67 80 00 00
+```

dsl/README.md

@@ -1,10 +1,13 @@
-# Руководство по конфигурации дизассемблера для добавления поддержки расширений RISC-V
+# Добавление поддержки новых расширений RISC-V
 
 ## Файлы
 
 `.yml`-файлы в этом каталоге используются для описания форматов инструкций RISC-V.
 
-В `schema.json` описана JSON-схема `.yml`-файлов, с помощью которой популярные редакторы и IDE могут их валидировать. 
+В `schema.json` описана JSON-схема `.yml`-файлов. WebStorm имеет встроенную поддержку валидации по JSON-схеме, в VS Code установите плагин для поддержки YAML.
+
+> [!IMPORTANT]
+> После редактирования инструкций запустите `npx tsx app/src/generator/run.ts`
 
 ## Формат файла
 
@@ -48,7 +51,7 @@
   (128-битная разрядность не полностью поддерживается дизассемблером);
 - `instructions` — список с описаниями инструкций
 
-Каждая инструкция описываетcя следующими полями:
+Каждая инструкция описывается следующими полями:
 - `mnemonic` — мнемоника инструкции, например `addi` или `c.j` (обязательно)
 - `fields` — список строк, отсылающие к значениям из `Fields` (обязательно)
 - `args` — список строк, отсылающие к значениям `Args`