doc: README decoration

2026-05-15 16:41:18 +03:00
parent 4f82a27cb7
commit 10dc60b54f
4 changed files with 373 additions and 13 deletions
--- a/designs/reflectometer_base/README.md
+++ b/designs/reflectometer_base/README.md
@ -0,0 +1,145 @@
+# Рефлектометр
+
+Модуль представляет собой законченную встраиваемую систему рефлектометра, объединяющую:
+
+- контроллер управления
+- генератор импульсов (DAC path)
+- сэмплер данных (ADC path)
+- аккумулятор и обработчик данных
+
+Система предназначена для формирования импульсов, синхронного сбора отраженного сигнала, накопления результатов и передачи обработанных данных во внешнюю систему.
+
+Данный модуль является полноценным интегрируемым блоком, который может использоваться как самостоятельная аппаратная подсистема внутри более крупного проекта.
+
+---
+
+## Назначение системы
+
+Основная задача системы:
+
+1. Получить параметры измерения через AXI Stream
+2. Сформировать последовательность импульсов на DAC
+3. Выполнить синходную выборку данных с ADC
+4. Накопить и обработать результаты
+5. Передать итоговые данные обратно через AXI Stream
+
+Таким образом реализуется полный цикл измерения без необходимости внешнего управления отдельными блоками.
+
+---
+
+## Состав системы
+
+### Controller
+
+Принимает входные команды по AXI Stream (Ethernet RX), декодирует параметры измерения и управляет всеми внутренними модулями системы.
+
+Формирует:
+
+- запуск генератора (`dac_start`)
+- запуск аккумулятора (`adc_start`)
+- параметры импульсов DAC
+- параметры выборки ADC
+- локальные reset-сигналы
+
+---
+
+### Generator
+
+Формирует последовательность импульсов на DAC с заданными:
+
+- амплитудой
+- длительностью
+- периодом
+- количеством повторений
+
+Для каждого импульса инициирует запуск выборки в сэмплере.
+
+---
+
+### Sampler
+
+Выполняет синхронный сбор данных с ADC по запросу генератора.
+
+Поддерживает:
+
+- фильтрацию `out_of_range`
+- упаковку данных
+- преобразование типа кода ( прямой или дополнительный)
+
+---
+
+### Accumulator
+
+Получает поток данных от сэмплера, выполняет накопление, усреднение и оконную обработку, после чего формирует пакеты для передачи результата.
+
+---
+
+## Управление системой
+
+Пользователь взаимодействует только с контроллером через AXI Stream-интерфейс.
+
+Прямое управление генератором, сэмплером и аккумулятором не требуется.
+
+---
+
+## Clock Domain Crossing (CDC)
+
+Система работает в нескольких тактовых доменах:
+
+- Ethernet RX (`gmii_rx_clk`)
+- Ethernet TX (`gmii_tx_clk`)
+- DAC (`dac_clk`)
+- ADC (`adc_clk`)
+
+Для корректной синхронизации между DAC и ADC используются специальные CDC-регистры для сигналов:
+
+- `sample_req`
+- `sample_done`
+
+Это обеспечивает безопасную передачу handshake-сигналов между тактовыми доменами.
+
+---
+
+## Список параметров
+
+### DAC_DATA_WIDTH
+Ширина выходных данных отправляемых на ЦАП.
+
+### ZERO_LEVEL
+Уровень сигнала в состоянии отсутствия импульса (базовый уровень сигнала).
+
+Типовые значения:
+
+- `8192` — середина диапазона ЦАП
+- `0` — нулевой уровень
+
+### ADC_DATA_WIDTH
+Ширина входных данных, получаемых с АЦП.
+
+### PACK_FACTOR
+Количество отсчетов, собираемых в один выходной пакет.
+
+### PROCESS_MODE
+Режим интерпретации входного кода:
+
+- `0` — прямой код
+- `1` — дополнительный код
+
+### ACCUM_WIDTH 
+Размер данных для аккумуляции, должен быть степенью числа 2. По умолчанию - 32
+
+### N_MAX 
+Максимальное число окон в последовательности. Должно быть степенью числа 2. Влияет на размер используемой памяти.
+
+### WINDOW_SIZE 
+Размер окна усреднения
+
+### PACKET_SIZE 
+Размер выходного пакета
+
+---
+
+## Сборка
+```make all``` - собрать все до битстрима
+
+```make vivado``` - открыть проект в Vivado
--- a/rtl/generator/README.md
+++ b/rtl/generator/README.md
@ -0,0 +1,91 @@
+# Генератор
+
+Модуль выполняет задачу формирования последовательности импульсов заданной амплитуды, длительности и периода.  
+Дополнительно реализован механизм синхронизации с модулем сэмплера через сигналы `sample_req` и `sample_done`, позволяющий запускать сбор данных для каждого импульса и ожидать подтверждения завершения выборки перед переходом к следующему импульсу.
+
+---
+
+## Список параметров
+
+### DATA_WIDTH
+Ширина выходных данных генератора.
+
+### ZERO_LEVEL
+Уровень сигнала в состоянии отсутствия импульса (базовый уровень сигнала).
+
+Типовые значения:
+
+- `8192` — середина диапазона ЦАП
+- `0` — нулевой уровень
+
+---
+
+## Список входных портов
+
+### clk_in
+Сигнал тактирования модуля.
+
+### rst
+Сброс модуля и остановка генерации.
+
+### start
+Сигнал запуска последовательности импульсов.
+
+При его активации модуль фиксирует все входные параметры и начинает генерацию.
+
+Повторный запуск во время активной генерации блокируется с помощью внутреннего сигнала `enable`.
+
+### [31:0] pulse_width
+Длительность активной части импульса (в тактах).
+
+### [31:0] pulse_period
+Полный период импульса (в тактах).
+
+### [DATA_WIDTH-1:0] pulse_height
+Амплитуда импульса.
+
+### [15:0] pulse_num
+Количество импульсов, которое необходимо сгенерировать.
+
+### sample_done
+Сигнал подтверждения от сэмплера о завершении выборки данных для текущего импульса.
+
+---
+
+## Список выходных портов
+
+pulse
+Выходной сигнал разрешения записи сигнала 
+
+[DATA_WIDTH-1:0] pulse_height_out
+Выходное значение амплитуды сигнала.
+
+Во время активной части импульса равно `pulse_height`, вне импульса — `ZERO_LEVEL`.
+
+sample_req
+Сигнал запроса на запуск выборки в модуле сэмплера.
+
+Поднимается в начале каждого нового импульса и снимается после получения `sample_done`.
+
+---
+
+## Логика работы
+
+После прихода сигнала `start` модуль:
+
+- фиксирует входные параметры генерации
+- сбрасывает внутренние счетчики
+- поднимает `enable = 1`
+- формирует первый `sample_req`
+
+После этого начинается последовательная генерация импульсов.
+
+---
+
+## Симуляция
+Тесты запускаются автоматически через make.
+```
+cd tests
+make sim
+```
+При успешном завершении теста высвечивается "ALL PASSED".
--- a/rtl/generator/tests/generator_tb.sv
+++ b/rtl/generator/tests/generator_tb.sv
@ -82,17 +82,25 @@ module generator_tb;

        repeat(40) @(posedge clk);
        
-         pulse_width  = 3;
+        pulse_width  = 3;
        pulse_period = 8;
        pulse_num    = 4;
        pulse_height = 14'h3FF;
        start = 1;

+       repeat(1) @(posedge clk);
+        start = 0;
+        
+        repeat(5) @(posedge clk);
+        start = 1;
+        pulse_height = 14'h155;
+
       repeat(1) @(posedge clk);
        start = 0;
        
        repeat(50) @(posedge clk);

+
        $display("\n=== TEST FINISHED ===");
        $finish;
    end
--- a/rtl/sampler/README.md
+++ b/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.