docs: добавил README с основной информацией по использованию

fix: исправлена ошибка кодировки при чтении файл

LICENSE

@@ -1,14 +1,10 @@
-            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
-                    Version 2, December 2004
-
- Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
-
- Everyone is permitted to copy and distribute verbatim or modified
- copies of this license document, and changing it is allowed as long
- as the name is changed.
-
-            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
-   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
-  0. You just DO WHAT THE FUCK YOU WANT TO.
+Permission to use, copy, modify, and/or distribute this software for
+any purpose with or without fee is hereby granted.
 
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE
+FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
+DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -0,0 +1,54 @@
+# DP32-proto
+
+Прототип эмулятора процессора DP32
+
+## Описание
+
+Это проект программной эмуляции и отладки процессора DP32 на языке python. В этом проекте можно найти 2 компонента - отладчик dp32dbg и эмулятор dp32emu. Первый полностью опирается на отладочную информацию в следующем формате. Это очень простой отладчик и очень нестабильный, поскольку писался с упором на скорость, а не на качество.
+
+```json
+{
+    "src": "absolute/path/to/source"
+    "labels" : {
+        "label1": 1
+        "label2": 2
+        ...
+    },
+    "instructions" : {
+        "<offset-in-words>" : {
+        "lenght": 2,
+        "srcline": 3
+        }
+        ...
+    }
+}
+```
+
+## Установка
+
+Стяните данный репозиторий и выполните в корне проекта команду `pip install .`
+
+## Использование
+
+После установки у вас появятся 2 программы:
+
+- dp32emu - программный эмулятор процессора dp32. Принимает на вход бинарный файл с командами dp32, выполняет их и в результате своей работы выдает дамп памяти процессора после завершения работы
+- dp32dbg - отладчик, опирающийся на вышеуказанный эмулятор. Позволяет выполнять действия пошаговой отладки и предоставляет базовую функциональность точек останова (но с ньюансами)
+
+Посмотреть инструкцию по запуску проще всего передав флаг `-h` каждой из этих программ
+
+## Использование отладчика
+
+help не встроен в отладчик, поскольку до этого его функционал не был документирован. Приведу здесь основной набор команд отладчика
+
+- `step/s` - выполняет одну инструкцию, на которую сейчас указывает регистр pc виртуальной машины
+- `breakpoint <lineno>` - устанавливает точку останова на определенной строке исходного кода. С точками останова 2 ньюанса:
+    1. Они они не могут быть установлены на комментарии или пустые строки. Если на строке больше одной операции, точка будет установлена на самую раннюю
+    2. Когда виртуальная машина встретит точку останова, временно она не сможет выполнять команду continue, поскольку не предусмотрено ротации точек останова. Если нужно продолжить выполнение программы дальше - выполните одну команду step
+- `continue/c` - выполняет программу до ближайшей точки останова
+- `reset` - сбрасывает состояние виртуальной машины и ее память, но не точки останова
+- `run` - сбрасывает состояние виртуальной машины и запускает выполнение кода
+- `cbp` - очищает все точки останова
+- `print/p <reg>` - печатает содержимое регистров. Регистры записываются в формате `r1-r255`,  позволяет также посмотреть адреса меток (указав название меток в качестве параметра) и системные регистры: pc, cc
+- `inspect/i <size> <amount> <place>` - печатает содержимое памяти по определенному адресу в определенном формате (строчная - знаковые, заглавная - беззнаковые): b/B - байт, h/H - полуслова - 16 бит, w/W - слова - 32 бита. `amount` - количество подряд идущих ячеек, содержимое которых нужно прочитать. `place` - место, с которого следует начать печать. Можеть представлять собой либо имя метки, либо полный адрес в десятичной или 16-ричной системе счисления
+

src/dp32proto/README.md

@@ -1,3 +1,4 @@
-# почему так грязно?
+# Почему такая некрасивая структура
+
+Этот репозиторий нужен был для того, чтобы отладить программу для процессора DP32. Структура проекта сделана такой для того, чтобы сократить время, необходимое на структуризацию и разрешение зависимостей.
 
-Потому что я заколебался воевать с модульностью питона, чтобы сделать это красиво

src/dp32proto/dbg.json

@@ -0,0 +1,98 @@
+{
+  "labels": {
+    "_start": 0,
+    "_start_return": 9,
+    "f_fibo": 11,
+    "f_fibo_loop": 14,
+    "return": 27,
+    "result": 28,
+    "end": 29
+  },
+  "instructions": {
+    "0": {
+      "length": 1,
+      "srcline": 6
+    },
+    "1": {
+      "length": 1,
+      "srcline": 7
+    },
+    "2": {
+      "length": 2,
+      "srcline": 8
+    },
+    "4": {
+      "length": 2,
+      "srcline": 9
+    },
+    "6": {
+      "length": 2,
+      "srcline": 10
+    },
+    "8": {
+      "length": 1,
+      "srcline": 11
+    },
+    "9": {
+      "length": 2,
+      "srcline": 13
+    },
+    "11": {
+      "length": 1,
+      "srcline": 16
+    },
+    "12": {
+      "length": 1,
+      "srcline": 17
+    },
+    "13": {
+      "length": 1,
+      "srcline": 18
+    },
+    "14": {
+      "length": 1,
+      "srcline": 20
+    },
+    "15": {
+      "length": 1,
+      "srcline": 21
+    },
+    "16": {
+      "length": 1,
+      "srcline": 22
+    },
+    "17": {
+      "length": 1,
+      "srcline": 23
+    },
+    "18": {
+      "length": 1,
+      "srcline": 24
+    },
+    "19": {
+      "length": 2,
+      "srcline": 25
+    },
+    "21": {
+      "length": 2,
+      "srcline": 27
+    },
+    "23": {
+      "length": 2,
+      "srcline": 28
+    },
+    "25": {
+      "length": 2,
+      "srcline": 29
+    },
+    "27": {
+      "length": 1,
+      "srcline": 31
+    },
+    "28": {
+      "length": 1,
+      "srcline": 32
+    }
+  },
+  "src": "C:\\Users\\etdia\\code\\dp32-proto\\src\\test.dasm"
+}

src/dp32proto/dbg_main.py

@@ -51,7 +51,7 @@ def main():
         dbg_dict: DbgDict = parse_dbg(json.load(f))
 
     dbg = Debugger(mem, dbg_dict)
-    with open (dbg_dict["src"], 'r') as f:
+    with open (dbg_dict["src"], 'r', encoding="utf8") as f:
         src = f.read()
 
     dbg_tui.run_tui(dbg, src)

src/dp32proto/dpdebugger.py

@@ -55,7 +55,7 @@ class Debugger:
             }
 
     def __init__(self, mem: bytearray, dbg_dict: DbgDict):
-        with open(dbg_dict["src"], 'r') as f:
+        with open(dbg_dict["src"], 'r', encoding="utf8") as f:
             self._source_lines = f.readlines()
         self._vm = VM(mem)
         self._dbg_dict = dbg_dict