From 10dc60b54f67493df5600d13f1ce8013ba76a6b0 Mon Sep 17 00:00:00 2001 From: otroubi Date: Fri, 15 May 2026 16:41:18 +0300 Subject: [PATCH] doc: README decoration --- designs/reflectometer_base/README.md | 145 +++++++++++++++++++++++++++ rtl/generator/README.md | 91 +++++++++++++++++ rtl/generator/tests/generator_tb.sv | 10 +- rtl/sampler/README.md | 140 +++++++++++++++++++++++--- 4 files changed, 373 insertions(+), 13 deletions(-) create mode 100644 designs/reflectometer_base/README.md create mode 100644 rtl/generator/README.md diff --git a/designs/reflectometer_base/README.md b/designs/reflectometer_base/README.md new file mode 100644 index 0000000..f6d0c19 --- /dev/null +++ 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 diff --git a/rtl/generator/README.md b/rtl/generator/README.md new file mode 100644 index 0000000..f776272 --- /dev/null +++ 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". diff --git a/rtl/generator/tests/generator_tb.sv b/rtl/generator/tests/generator_tb.sv index 55e51f6..2fdeb95 100644 --- a/rtl/generator/tests/generator_tb.sv +++ b/rtl/generator/tests/generator_tb.sv @@ -82,7 +82,7 @@ module generator_tb; repeat(40) @(posedge clk); - pulse_width = 3; + pulse_width = 3; pulse_period = 8; pulse_num = 4; pulse_height = 14'h3FF; @@ -90,9 +90,17 @@ module generator_tb; 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 diff --git a/rtl/sampler/README.md b/rtl/sampler/README.md index 751865c..9940a44 100644 --- 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.