doc: README decoration

rtl/sampler/README.md

@@ -1,23 +1,139 @@
 # Сэмплер
-Модуль выполняет задачу сбора данных с выхода АЦП, их обработку, упаковку, и передачу дальше с помощью AXI Stream интерфейса.
 
-## Cписок параметров
-DATA_WIDTH - ширина входных данных, получаемых с АЦП.
-PACK_FACTOR - количество отсчетов, собираемых в один выходной пакет.
-PROCESS_MODE - режим интерпретации входного кода. 0 - прямой код, 1 - дополнительный код.
+Модуль выполняет задачу сбора данных с выхода АЦП, их обработки, упаковки и передачи дальше с помощью AXI Stream интерфейса.  
+Дополнительно реализован механизм синхронизации с внешним генератором через сигналы `sample_req` и `sample_done`, позволяющий запускать сбор строго по запросу и подтверждать завершение выборки.
+
+---
+
+## Список параметров
+
+DATA_WIDTH
+Ширина входных данных, получаемых с АЦП.
+
+PACK_FACTOR
+Количество отсчетов, собираемых в один выходной пакет.
+
+PROCESS_MODE
+Режим интерпретации входного кода:
+
+- `0` — прямой код
+- `1` — дополнительный код
+
+---
 
 ## Список входных портов
-clk_in - сигнал тактирования выходного интерфейса.
-rst - сброс модуля и остановка подачи импульсов.
-[DATA_WIDTH-1:0] data_in - входной сигнал с АЦП.
-out_of_range - флаг выхода значений данных за допустимый диапазон. 0 - валидны, 1 - не валидны.
+
+clk_in
+Сигнал тактирования выходного интерфейса.
+
+rst
+Сброс модуля и остановка работы.
+
+[DATA_WIDTH-1:0] data_in
+Входной сигнал с АЦП.
+
+out_of_range
+Флаг выхода значений данных за допустимый диапазон:
+
+- `0` — данные валидны
+- `1` — данные невалидны и игнорируются
+
+[31:0] smp_num
+Количество валидных отсчетов, которое необходимо собрать после получения запроса на выборку.
+
+sample_req
+Сигнал запроса на запуск выборки.  
+При его активации модуль начинает сбор данных и переходит в активное состояние (`enable = 1`).
+
+---
 
 ## Список выходных портов
-[DATA_WIDTH*PACK_FACTOR-1:0]  m_axis_tdata - урезанный axis формат, выходные данные. Ширина шины считается исходя из битности данных и фактора упаковки.
-m_axis_tvalid - урезанный axis формат, валидность выходных данных.
+
+[DATA_WIDTH*PACK_FACTOR-1:0] m_axis_tdata
+Урезанный AXI Stream формат, выходные данные.  
+Ширина шины определяется как произведение битности данных и фактора упаковки.
+
+m_axis_tvalid
+Урезанный AXI Stream формат, сигнал валидности выходных данных.  
+Формируется при готовности очередного пакета.
+
+sample_done
+Сигнал завершения выборки.  
+Поднимается после того, как модуль собрал количество валидных отсчетов, равное `smp_num`.
+
+---
 
 ## Логика работы
-На каждом такте принимаются data_in (значение АЦП) и out_of_range (флаг выхода значений данных за допустимый диапазон). Если out_of_range = 1, то данные игнорируются и не попадают во внутренний буффер. В противном случае, модуль накапливает данные во внутреннем буффере, идет его заполнение до количества данных, равное PACK_FACTOR. Когда буффер оказывается заполненным, он выдает пакет упакованных данных, сопровождая их импульсом m_axis_tvalid (готовность пакета). Если PROCESS_MODE = 1, данные выдаются в дополнительном коде, если PROCESS_MODE = 0 - в прямом.
+
+На каждом такте принимаются:
+
+- `data_in` — значение АЦП
+- `out_of_range` — флаг допустимости значения
+
+Если `out_of_range = 1`, данные считаются невалидными, игнорируются и не попадают во внутренний буфер.
+
+Если `out_of_range = 0`, данные считаются корректными и используются для дальнейшей обработки.
+
+---
+
+### Преобразование данных
+
+Если `PROCESS_MODE = 1`, входные данные интерпретируются как дополнительный код и преобразуются перед упаковкой.
+
+Если `PROCESS_MODE = 0`, данные передаются без преобразования (прямой код).
+
+---
+
+### Запуск выборки
+
+Сбор данных начинается только после прихода сигнала `sample_req`.
+
+При этом:
+
+- фиксируется значение `smp_num`
+- внутренний счетчик собранных отсчетов обнуляется
+- модуль переходит в активное состояние (`enable = 1`)
+
+Пока `enable = 1`, модуль принимает только валидные отсчеты и считает их.
+
+---
+
+### Упаковка данных
+
+Внутренний буфер заполняется до количества данных, равного `PACK_FACTOR`.
+
+#### Если `PACK_FACTOR = 1`
+
+Каждый валидный отсчет сразу формирует выходной пакет:
+
+- данные передаются в `m_axis_tdata`
+- формируется импульс `m_axis_tvalid`
+
+#### Если `PACK_FACTOR > 1`
+
+Данные последовательно накапливаются во внутреннем сдвиговом буфере.
+
+Когда буфер полностью заполнен:
+
+- формируется пакет упакованных данных
+- поднимается `m_axis_tvalid`
+
+После этого начинается сбор следующего пакета.
+
+---
+
+### Завершение выборки
+
+Когда количество собранных валидных отсчетов достигает значения `smp_num`:
+
+- поднимается сигнал `sample_done`
+- внутренние счетчики сбрасываются
+- буфер очищается
+- `enable` сбрасывается в `0`
+
+Это означает полное завершение текущего цикла выборки.
+
+---
 
 ## Симуляция
 Тесты запускаются автоматически через make.