Generate README.md, add clock dividers and limiters, load configs from WS client, fix stream per-segment subscriptions according to memory projections mechanism
This commit is contained in:
250
README.md
Normal file
250
README.md
Normal file
@@ -0,0 +1,250 @@
|
||||
# hmmmm
|
||||
|
||||
**Модульный эмулятор микроконтроллеров с сетевым интерфейсом**
|
||||
|
||||
hmmmm — это эмулятор микроконтроллеров, который позволяет эмулировать AVR и другие архитектуры с возможностью управления через WebSocket. Эмулятор поддерживает динамическую загрузку устройств, композицию сложных устройств и потоковую передачу изменений памяти в реальном времени.
|
||||
|
||||
## Возможности
|
||||
|
||||
- **Эмуляция AVR-микроконтроллеров** — поддержка ~99 инструкций AVR
|
||||
- **Модульная архитектура** — устройства загружаются как динамические библиотеки (.so)
|
||||
- **Композиция устройств** — создание сложных устройств через TOML-конфигурацию
|
||||
- **WebSocket интерфейс** — управление эмуляцией и получение данных в реальном времени
|
||||
- **Потоковая передача** — подписка на изменения памяти (чтение/запись)
|
||||
- **Аутентификация** — SHA-512 токен с временным окном (TOTP-подобный)
|
||||
- **Сегментированная память** — PS (программная), GP_REGS, IO_REGS, DS (данные)
|
||||
|
||||
## Структура проекта
|
||||
|
||||
```
|
||||
hmmmm/
|
||||
├── src/ # Исходный код эмулятора
|
||||
│ ├── main.c # WebSocket сервер, главный цикл
|
||||
│ ├── hmmmm.c # Загрузка динамических библиотек
|
||||
│ ├── config.c # Парсинг TOML-конфигураций
|
||||
│ └── proto/ # Обработчики WebSocket-протокола
|
||||
├── inc/ # Заголовочные файлы
|
||||
├── devices/ # Реализации эмулируемых устройств
|
||||
│ ├── avr_generic/ # Универсальный эмулятор AVR
|
||||
│ └── avr_gpio/ # GPIO устройство
|
||||
├── flatbuffers/ # FlatBuffers схемы протокола
|
||||
├── deps/ # Внешние зависимости
|
||||
├── hmmmm_scripts/ # Python скрипты и утилиты
|
||||
└── Makefile # Основной файл сборки
|
||||
```
|
||||
|
||||
## Требования
|
||||
|
||||
- **GCC** с поддержкой C23
|
||||
- **OpenSSL** (для SHA-512)
|
||||
- **Git** (для клонирования зависимостей)
|
||||
- **Python 3.12+** (опционально, для скриптов)
|
||||
|
||||
## Сборка
|
||||
|
||||
### 1. Инициализация зависимостей
|
||||
|
||||
```bash
|
||||
# Клонирование и сборка внешних зависимостей
|
||||
make deps
|
||||
```
|
||||
|
||||
Это клонирует следующие зависимости в `deps/`:
|
||||
- `tomlc99` — TOML парсер
|
||||
- `ptQueue` — lock-free очередь
|
||||
- `wsServer` — WebSocket сервер
|
||||
- `flatcc` — FlatBuffers runtime для C
|
||||
- `flatbuffers` — Google FlatBuffers (flatc компилятор)
|
||||
|
||||
### 2. Генерация FlatBuffers кода
|
||||
|
||||
```bash
|
||||
# Генерация C заголовков из .fbs схем
|
||||
make proto
|
||||
|
||||
# Генерация Python bindings (опционально)
|
||||
make python-proto
|
||||
```
|
||||
|
||||
### 3. Сборка эмулятора
|
||||
|
||||
```bash
|
||||
# Основная сборка
|
||||
make build
|
||||
|
||||
# Полная пересборка
|
||||
make rebuild
|
||||
|
||||
# Очистка
|
||||
make clean
|
||||
```
|
||||
|
||||
После успешной сборки исполняемый файл будет находиться в `out/main.elf`.
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
### 1. Подготовка конфигурации
|
||||
|
||||
Создайте TOML-файл с конфигурацией эмулятора:
|
||||
|
||||
```toml
|
||||
# example.toml
|
||||
[dev]
|
||||
avr = "devices/avr_generic/AVRrc.toml"
|
||||
|
||||
[clock]
|
||||
limiter = 16000000 # 16 MHz
|
||||
|
||||
[mem]
|
||||
# Настройка памяти
|
||||
```
|
||||
|
||||
### 2. Запуск эмулятора
|
||||
|
||||
```bash
|
||||
./out/main.elf example.toml
|
||||
```
|
||||
|
||||
Эмулятор запустит WebSocket сервер на порту **8181**.
|
||||
|
||||
### 3. Подключение клиента
|
||||
|
||||
Используйте Python-клиент для подключения:
|
||||
|
||||
```bash
|
||||
cd ../hmmmm_client_py
|
||||
poetry install
|
||||
poetry run python -m model.client
|
||||
```
|
||||
|
||||
## Конфигурация
|
||||
|
||||
### TOML-конфигурация устройства
|
||||
|
||||
Пример конфигурации AVR устройства:
|
||||
|
||||
```toml
|
||||
[device]
|
||||
type = "avr_generic"
|
||||
libpath = "devices/avr_generic/AVRrc_build/device.so"
|
||||
firmware = "test.bin"
|
||||
|
||||
[memory]
|
||||
ps_size = 65536 # Program space
|
||||
ds_size = 4096 # Data space
|
||||
io_regs = 256 # I/O registers
|
||||
gp_regs = 32 # General purpose registers
|
||||
```
|
||||
|
||||
### Композиция устройств
|
||||
|
||||
Сложные устройства создаются через композицию:
|
||||
|
||||
```toml
|
||||
[dev]
|
||||
core = "avr_generic.toml"
|
||||
gpio_a = "avr_gpio.toml"
|
||||
|
||||
[clock]
|
||||
limiter = 16000000
|
||||
|
||||
[mem.intercept.PORTA]
|
||||
base_at = "core"
|
||||
point_at = "gpio_a"
|
||||
addr = 0
|
||||
seg = "reg_io"
|
||||
```
|
||||
|
||||
## Протокол
|
||||
|
||||
Эмулятор использует **FlatBuffers over WebSocket** для обмена сообщениями.
|
||||
|
||||
### Типы сообщений
|
||||
|
||||
#### Клиент → Сервер:
|
||||
- **AuthRequest** — аутентификация (SHA-512 токен + timestamp)
|
||||
- **ExecCtrlMessage** — управление эмуляцией (старт/стоп/сброс)
|
||||
- **MemReadRequest/MemWriteRequest** — операции с памятью
|
||||
- **StreamRegRequest** — подписка на изменения памяти
|
||||
|
||||
#### Сервер → Клиент:
|
||||
- **AuthResponse** — подтверждение аутентификации (seat_id)
|
||||
- **ExecNotifyMessage** — уведомления о состоянии эмуляции
|
||||
- **MemReadResponse** — данные из памяти
|
||||
- **StreamDataPush** — потоковые изменения памяти
|
||||
|
||||
### Аутентификация
|
||||
|
||||
```python
|
||||
import hashlib
|
||||
import time
|
||||
|
||||
def generate_auth(access_token: str) -> bytes:
|
||||
now = int(time.time())
|
||||
prepared = f'{access_token}{now // 30}'
|
||||
return hashlib.sha512(prepared.encode()).digest()
|
||||
```
|
||||
|
||||
Токен действителен в течение 30 секунд.
|
||||
|
||||
## API устройств
|
||||
|
||||
Каждое устройство должно экспортировать интерфейс `device_lib_t`:
|
||||
|
||||
```c
|
||||
typedef struct {
|
||||
uint8_t devType;
|
||||
device_public_context_t* (*init)(void*, char* errbuf);
|
||||
uint8_t (*makeDeviceTick)(device_public_context_t* devInfo);
|
||||
void* extendedHandlers;
|
||||
void* (*parseSpecsFromConfig)(const conf_dev_t* devConf, char* errbuf);
|
||||
void (*freeSpecs)(void* specs);
|
||||
void (*freeDevMem)(device_mem_t* mem);
|
||||
void (*fillSmartReadSpecs)(void* specs, smart_read_spec_t*, uint64_t);
|
||||
void (*fillSmartWriteSpecs)(void* specs, smart_write_spec_t*, uint64_t);
|
||||
} device_lib_t;
|
||||
```
|
||||
|
||||
## Отладка
|
||||
|
||||
### Генерация compile_commands.json
|
||||
|
||||
Для интеграции с clangd:
|
||||
|
||||
```bash
|
||||
./.gen_compile_commands.sh
|
||||
```
|
||||
|
||||
### Логирование
|
||||
|
||||
Эмулятор выводит отладочную информацию в stdout. Для подробного логирования можно модифицировать `src/main.c`.
|
||||
|
||||
### GDB
|
||||
|
||||
```bash
|
||||
gdb ./out/main.elf
|
||||
(gdb) run example.toml
|
||||
```
|
||||
|
||||
## Производительность
|
||||
|
||||
- **Тактовая частота** — до 16 MHz (эмулируемая)
|
||||
- **WebSocket** — асинхронная отправка сообщений
|
||||
- **Lock-free очереди** — эффективный межпоточный обмен
|
||||
- **FlatBuffers** — сериализация с нулевым копированием
|
||||
|
||||
## Известные ограничения
|
||||
|
||||
- Абсолютные пути в конфигурационных файлах (требует замены на относительные)
|
||||
- Хардкод токена аутентификации (требует выноса в ENV)
|
||||
- Отсутствие graceful shutdown (обработка SIGINT/SIGTERM)
|
||||
- Нет unit-тестов для основного кода
|
||||
|
||||
## Лицензия
|
||||
|
||||
Проект разработан @nikto_b. Все права защищены.
|
||||
|
||||
## Контакты
|
||||
|
||||
- Документация: https://about.hmmmm.nikto-b.ru/
|
||||
- Автор: @nikto_b
|
||||
Reference in New Issue
Block a user