# Декодеры DSView для шин 96-контактного интерфейса

Два независимых декодера: **Plates PBus** и **Plates SBus**. Показывают
адрес устройства, регистр, сырые 16-битные данные, результат проверок
и итог каждого обращения. Повторные одинаковые обращения выводятся отдельно.

Декодеры устанавливаются в DSView и разбирают цифровой захват шин,
используемых с SETGUI. Формат взят из `ParallelBusSlave_ver_2_0.vhd`
и `SerialBusSlave_ver_2_0.vhd` из `ip_repo` репозитория PlatesSim. Зависимости
от установленного SETGUI или PlatesConf нет. Число 96 относится
к разъёму; ширина данных PBus составляет 16 бит.

## Установка

1. Закрыть DSView.
2. Скопировать обе папки `plates_pbus` и `plates_sbus` из `decoders`
   в каталог `decoders` используемой установки DSView. Внутри каждой
   папки должны непосредственно лежать `__init__.py` и `pd.py`.
3. Открыть DSView, загрузить захват или получить новый.
4. В списке декодеров выбрать **Plates PBus** либо **Plates SBus**
   и назначить соответствующие каналы анализатора. При одновременном
   захвате обеих шин добавить оба декодера.

Используется sigrok API 3 и синтаксис Python 3.6+. Формат декодеров
сверён со штатными пакетами установленного DSView и
[исходниками DSView](https://github.com/DreamSourceLab/DSView/tree/master/libsigrokdecode4DSL/decoders).
Общие сведения о пользовательских декодерах — в
[инструкции производителя](https://dreamsourcelab.cn/logic-analyzer/protocol_decoder_howto/).

## Каналы PBus

| Сигнал декодера | Подключение | Назначение |
| --- | --- | --- |
| PBCE | `pbce` | Низкий уровень разрешает транзакцию |
| PBACK | `pback` | Подтверждения адреса, данных и инверсии |
| D0…D15 | `pbdata[0]`…`pbdata[15]` | Все 16 разрядов общей двунаправленной шины |
| PBCLK | `pbclk`, необязательно | Проверка уровня тактовой линии в фазах ответа |

Для полного декодирования PBus требуется **18 каналов**, с PBCLK — 19.
Анализатор на 16 каналов не захватит полный набор одновременно.
Назначать D0…D15 по номерам разрядов шины, а номера контактов
96-контактного разъёма брать из схемы конкретной платы.

Операция начинается со спада PBCE. Первый спад PBACK подтверждает адрес:
`PBDATA[15:8] = dev*16 + reg`, `PBDATA[7:0] = ~PBDATA[15:8]`.
Следующий подъём PBACK подтверждает 16-битные данные; следующий спад —
их 16-битную инверсию. При назначенном PBCLK данные должны подтверждаться
при CLK=0, инверсия — при CLK=1. Выборка слов выполняется по ACK.

Неверная инверсия адреса, неверная инверсия ответа, нарушение фазы CLK
и незавершённое ожидание ACK выводятся отдельными предупреждениями.
Снятие CE до завершения или конец захвата сохраняют частичную операцию
с признаком `complete=False`. Начальный фрагмент захвата с уже низким CE
пропускается до следующего полного начала транзакции.

## Каналы SBus

| Сигнал декодера | Подключение | Направление |
| --- | --- | --- |
| SBCLK | `sbclk` | Тактовая линия мастера |
| SBDATAIN | `sbdatain` | ТМС → платы |
| SBDATAOUT | `sbdataout` | Платы → ТМС |

Для SBus достаточно **трёх каналов**. Имена IN/OUT соответствуют
входу и выходу ведомого блока в HDL.

Кадр содержит 29 бит старшим вперёд: направление (0 — чтение,
1 — запись), устройство (4), регистр (4), данные (16), CRC (4).
Декодер выбирает биты по нарастающим фронтам SBCLK. Заголовок и данные
записи идут по SBDATAIN; данные чтения и CRC ответа — по SBDATAOUT.
CRC учитывает все 25 бит направления, адреса и данных, а затем
четыре завершающие единицы по алгоритму HDL. Это собственный алгоритм,
его нельзя заменять произвольным штатным CRC-4.

| Параметр | По умолчанию | Смысл |
| --- | --- | --- |
| Frame gap (us) | 3,6 мкс | Минимальное время неподвижного CLK для синхронизации нового кадра |
| Write ACK sampling delay (us) | 0,5 мкс | Задержка выборки SBDATAOUT после последнего бита CRC записи |

Пауза учитывается при обоих уровнях CLK. Значение 3,6 мкс взято
из текущих COUNT_RESET=180 и частоты блока SBus 50 МГц.
Задержка ACK 0,5 мкс — настраиваемая точка наблюдения после проверки CRC
и до сброса по паузе. Для другого ведомого или других времён обмена
параметры нужно согласовать с захватом. Межкадровая пауза должна превышать
длительность обычного неподвижного участка CLK внутри кадра;
задержка ACK должна быть положительной и меньше межкадровой паузы.

Низкий SBDATAOUT в точке выборки подтверждает запись. Высокий уровень
помечается `ACK HIGH (NACK / no response)`: по одному уровню нельзя
отличить отказ от отсутствия платы. CRC и ACK показываются независимо.
ACK frontend PlatesSim подтверждает CRC, но не доказывает помещение
команды в FIFO или её применение CPU1.

Если файл закончился до выборки ACK, полная запись сохраняется с `ack=None`.
Частичный кадр отмечается числом полученных битов; следующий кадр
синхронизируется после паузы. В начале захвата SBus ожидает наблюдаемую
паузу, чтобы фрагмент уже идущего обмена не стал ложным заголовком.
При записи включать в захват паузу перед первым кадром и время после CRC.

## Проверки и границы подтверждённого

Из корня репозитория:

```powershell
python -m unittest discover -s tools/dsview/tests -p test_plates_buses.py -v # Проверка декодеров на цифровых трассах без запуска DSView.
```

21 тест проверяет оба направления SBus, CRC, отдельную выборку ACK,
повторы, паузы обоих уровней, восстановление синхронизации, края диапазонов
PBus, обе инверсные проверки, фазы ACK, отсутствие каналов и обрывы захвата.
Среда тестов исполняет рабочие методы `decode()` и `end()` через подмену
API ожидания событий; сигналы формируются независимо от автоматов декодеров.
Дополнительно проверены синтаксис Python 3.6 и UTF-8 исходников.

Загрузка новых пакетов в интерфейсе DSView и захват физического обмена
с SETGUI пока не проверены. Номера контактов разъёма и соответствие каналам
анализатора задаются по фактическому подключению. Модели отдельных линий
TK/PWM/ACK в эти декодеры не входят.

Python-выход каждого декодера содержит `['FRAME', словарь]`. Общие поля:
`bus`, `operation`, `dev`, `reg`, `value`. У SBus отдельно доступны `crc`,
`crc_expected`, `crc_ok`, `ack`; у PBus — `address_word`, `address_ok`,
`inverse`, `inverse_ok`, `errors`, `complete`, `ok`.