Add shared Analog Devices ADC DDR readout framework

[bengineerd]

Description

Add a shared serialized DDR ADC readout framework and use it for the AD9249, AD9252, and AD9681. This consolidates device-independent capture, delay control, framing, pattern testing, calibration, simulation, and PyRogue support while retaining the AD9249-only legacy interface for downstream migration.

Details

• Adds common 7-Series and UltraScale ADC DDR PHYs, readout logic, debug/status interfaces, and calibration support.
• Replaces the previous AD9252 and AD9681 readout implementations with device wrappers around the shared framework.
• Separates the retained AD9249 legacy PyRogue implementation and documents firmware and software migration to the new interface.
• Adds device-level digital and pin-level simulation models and focused cocotb coverage for AD9249, AD9252, and AD9681.
• Implements each ADC's datasheet-defined configuration-transfer behavior in both PyRogue and the simulation models.
• Uses Python 3.10+ type hints and NumPy-style docstrings for the new PyRogue code.

Pin constraints are intentionally left to downstream top-level XDC files. Downstream consumer migrations and hardware validation will follow this release; the AD9681 path has been exercised successfully in VCS simulation.

Validation performed:

• Focused PyRogue model and calibration tests passed.
• Focused cocotb simulations passed, including all three ADC core and pin-level models.
• VSG reported no violations in the changed VHDL.
• Flake8 passed for the changed Python.
• Git diff whitespace checks passed.

[Copilot]

Pull request overview

This PR introduces a shared serialized DDR ADC readout framework under devices/AnalogDevices/adcDdr/ and migrates AD9249/AD9252/AD9681 readout + simulation + PyRogue support to use the common infrastructure (while keeping an AD9249 legacy software interface for downstream migration).

Changes:

• Added a common ADC DDR capture/PHY/core/pattern-test infrastructure (7-Series + UltraScale) with simulation helpers and wrappers.
• Reworked AD9249/AD9252/AD9681 readout RTL and added/updated pin-level + core-level simulation wrappers used by new cocotb tests.
• Added new PyRogue models for the normalized interface (and isolated the retained AD9249 legacy map), plus updated Python packaging requirements/docs.

Reviewed changes

Copilot reviewed 77 out of 79 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/devices/analog_devices/test_AdcDdrPatternTester.py	Cocotb test for the shared pattern tester via AXI-Lite wrapper.
tests/devices/analog_devices/test_AdcDdrPatternPkg.py	Cocotb test validating PN helpers in the shared pattern package.
tests/devices/analog_devices/test_Ad9681SimTiming.py	Cocotb timing/skew/jitter checks for AD9681 pin-level model.
tests/devices/analog_devices/test_Ad9681Sim.py	Cocotb functional pin-level test for AD9681 model + SPI behavior.
tests/devices/analog_devices/test_Ad9252SimTiming.py	Cocotb timing/skew/jitter checks for AD9252 pin-level model.
tests/devices/analog_devices/test_Ad9252SimCore.py	Cocotb register/pattern behavior checks for AD9252 core model.
tests/devices/analog_devices/test_Ad9252Sim.py	Cocotb functional pin-level test for AD9252 model + SPI staging.
tests/devices/analog_devices/test_Ad9249SimTiming.py	Cocotb timing/skew/jitter checks for AD9249 pin-level model.
tests/devices/analog_devices/test_Ad9249SimCore.py	Cocotb register/pattern behavior checks for AD9249 core model.
tests/devices/analog_devices/test_Ad9249Sim.py	Cocotb functional pin-level test for AD9249 dual-bank pin model + SPI bank isolation.
tests/devices/analog_devices/init.py	Package init for analog devices tests.
tests/devices/init.py	Package init for device tests.
setup.py	Enforces Python >= 3.10 for the surf Python package.
python/surf/devices/analog_devices/_AdcDdrPatternTester.py	New PyRogue model for the shared finite-window pattern tester.
python/surf/devices/analog_devices/_Ad9249Legacy.py	Adds legacy AD9249 PyRogue maps isolated from the normalized interface.
python/surf/devices/analog_devices/init.py	Re-exports new normalized + legacy Analog Devices PyRogue modules.
python/README.md	Documents Python >= 3.10 requirement and new PyRogue API style guidance.
devices/README.md	Links Analog Devices directory and references shared adcDdr infrastructure.
devices/AnalogDevices/ruckus.tcl	Loads new adcDdr and ad9252 manifests into the Analog Devices build.
devices/AnalogDevices/README.md	New overview of Analog Devices directory and adcDdr usage/migration notes.
devices/AnalogDevices/adcDdr/wrappers/AdcDdrPatternTesterWrapper.vhd	Flattened simulation wrapper exposing AdcDdrPatternTester over discrete AXI-Lite signals.
devices/AnalogDevices/adcDdr/wrappers/AdcDdrPatternPkgTb.vhd	Simulation wrapper exposing PN helpers from AdcDdrPatternPkg for cocotb.
devices/AnalogDevices/adcDdr/wrappers/AdcDdrCoreWrapper.vhd	Flattened simulation wrapper exposing AdcDdrCore over discrete AXI-Lite + stream signals.
devices/AnalogDevices/adcDdr/UltraScale/ruckus.tcl	UltraScale-family adcDdr manifest for PHY/deserializer sources.
devices/AnalogDevices/adcDdr/UltraScale/rtl/AdcDdrPhyUltraScale.vhd	UltraScale LVDS DDR PHY implementation using ISERDESE3 + IDELAYE3 wrapper.
devices/AnalogDevices/adcDdr/UltraScale/rtl/AdcDdrDeserializerUltraScale.vhd	UltraScale per-lane deserializer + delay + gearbox implementation.
devices/AnalogDevices/adcDdr/sim/AdcDdrPatternPkg.vhd	Shared PN9/PN23 helpers used by ADC simulation models.
devices/AnalogDevices/adcDdr/ruckus.tcl	Top-level adcDdr manifest loading RTL + sim and selecting per-family PHY sources.
devices/AnalogDevices/adcDdr/rtl/AdcDdrPkg.vhd	Defines normalized adcDdr register map constants and shared types/helpers.
devices/AnalogDevices/adcDdr/rtl/AdcDdrPhy.vhd	Device-family selector wrapping 7-Series vs UltraScale PHY implementations.
devices/AnalogDevices/adcDdr/7Series/ruckus.tcl	7-Series-family adcDdr manifest for PHY/deserializer sources.
devices/AnalogDevices/adcDdr/7Series/rtl/AdcDdrPhy7Series.vhd	7-Series LVDS DDR PHY implementation using ISERDESE2 + IDELAYE2.
devices/AnalogDevices/adcDdr/7Series/rtl/AdcDdrDeserializer7Series.vhd	7-Series per-lane deserializer + delay implementation.
devices/AnalogDevices/ad9681/wrappers/Ad9681SimWrapper.vhd	Flattened cocotb wrapper for AD9681 pin-level sim model.
devices/AnalogDevices/ad9681/wrappers/Ad9681SimCoreWrapper.vhd	Flattened wrapper for AD9681 core sim model.
devices/AnalogDevices/ad9681/sim/ruckus.tcl	Sim-only manifest for AD9681 simulation sources.
devices/AnalogDevices/ad9681/sim/Ad9681Serializer.vhd	Removes older serializer implementation (no longer used).
devices/AnalogDevices/ad9681/ruckus.tcl	Simplifies manifest to load sim manifest (removing old family selection).
devices/AnalogDevices/ad9681/core/Ad9681Readout.vhd	New AD9681 readout wrapper around the shared adcDdr core/PHY.
devices/AnalogDevices/ad9681/7Series/ruckus.tcl	Removes old 7-Series manifest (superseded by shared adcDdr PHY).
devices/AnalogDevices/ad9681/7Series/rtl/Ad9681Deserializer.vhd	Removes old AD9681 deserializer (superseded by shared adcDdr deserializer).
devices/AnalogDevices/ad9252/wrappers/Ad9252SimWrapper.vhd	Flattened cocotb wrapper for AD9252 pin-level sim model.
devices/AnalogDevices/ad9252/wrappers/Ad9252SimCoreWrapper.vhd	Flattened wrapper for AD9252 core sim model.
devices/AnalogDevices/ad9252/sim/ruckus.tcl	Sim-only manifest for AD9252 simulation sources.
devices/AnalogDevices/ad9252/sim/Ad9252Sim.vhd	New primitive-free pin-level AD9252 simulation model.
devices/AnalogDevices/ad9252/ruckus.tcl	New AD9252 manifest loading core + sim sources.
devices/AnalogDevices/ad9252/core/Ad9252Readout.vhd	New AD9252 readout wrapper around the shared adcDdr core/PHY.
devices/AnalogDevices/ad9252/core/Ad9252Pkg.vhd	Defines AD9252 serialized pin-interface record types.
devices/AnalogDevices/ad9252/core/Ad9252Config.vhd	Adds/retains AD9252 configuration support block under the new directory structure.
devices/AnalogDevices/ad9249/wrappers/Ad9249SimWrapper.vhd	Flattened cocotb wrapper for AD9249 pin-level sim model.
devices/AnalogDevices/ad9249/wrappers/Ad9249SimCoreWrapper.vhd	Flattened wrapper for AD9249 core sim model.
devices/AnalogDevices/ad9249/tb/Ad9249Group.vhd	Adjusts AD9249 TB configuration (binFormat change).
devices/AnalogDevices/ad9249/sim/ruckus.tcl	Sim-only manifest for AD9249 simulation sources.
devices/AnalogDevices/ad9249/ruckus.tcl	Loads AD9249 core as VHDL-2008 and adds sim manifest.
devices/AnalogDevices/ad9249/core/Ad9249ReadoutBank.vhd	New AD9249 per-bank readout wrapper around shared adcDdr core/PHY.
devices/AnalogDevices/ad9249/core/Ad9249Readout.vhd	New full-device AD9249 readout aggregating two independent banks under one AXI-Lite window.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 24.81%. Comparing base (c540eb7) to head (dee669a).
⚠️ Report is 9 commits behind head on pre-release.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@               Coverage Diff               @@
##           pre-release    #1466      +/-   ##
===============================================
- Coverage        25.19%   24.81%   -0.39%     
===============================================
  Files              291      302      +11     
  Lines            25956    28489    +2533     
===============================================
+ Hits              6540     7069     +529     
- Misses           19416    21420    +2004     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ruck314]

@bengineerd Approved but you should address the copilot review comments as well.

[bengineerd]

I've verified the AD9249 code with the LDMX hardware.