updated documentation (PS)

docs/ps_subsystem.md

@@ -8,13 +8,22 @@
 
 The PS subsystem is responsible for:
 
-- System initialization
+* System initialization
-- Configuring PL subsystems
+* Configuring PL subsystems
-- Triggering captures
+* Triggering captures
-- Receiving data via DMA
+* Receiving data via DMA
-- Preparing data for processing and visualization
+* Preparing data for processing and visualization
 
-The current implementation acts as a **placeholder for post-processing**, focusing on reliable data acquisition and host interaction.
+The subsystem now includes an initial **FrFT-based processing chain** implemented in Simulink and targeted to the RFSoC Processing System (PS).
+
+Current work focuses on:
+
+* Algorithm validation
+* Code generation
+* Hardware integration
+* Performance characterization
+
+while maintaining reliable data acquisition and host interaction.
 
 ---
 
@@ -22,31 +31,33 @@ The current implementation acts as a **placeholder for post-processing**, focusi
 
 ### Control & Initialization
 
-- Configure PL parameters:
+* Configure PL parameters:
-  - Tx waveform configuration
+
-  - Capture parameters (nFrames, etc.)
+  * Tx waveform configuration
-- Initialize DMA and memory buffers
+  * Capture parameters (nFrames, etc.)
-- Manage system startup
+* Initialize DMA and memory buffers
+* Manage system startup
 
 ---
 
 ### Trigger & Capture
 
-- Generates capture trigger (software-controlled)
+* Generates capture trigger (software-controlled)
-- Controls DPW acquisition timing
+* Controls DPW acquisition timing
-- Each trigger initiates one DPW capture
+* Each trigger initiates one DPW capture
 
 ---
 
 ### DMA Handling
 
-- AXI4-Stream → DMA (S2MM)
+* AXI4-Stream → DMA (S2MM)
-- Receives **128-bit stream** (4 samples per clock)
+* Receives **128-bit stream** (4 samples per clock)
-- Stores data in PS DDR memory
+* Stores data in PS DDR memory
 
 Configuration:
-- Frame size: 512 samples
+
-- nFrames: configurable (validated up to 1024)
+* Frame size: 512 samples
+* nFrames: configurable (validated up to 1024)
 
 ---
 
@@ -54,9 +65,9 @@ Configuration:
 
 ### Raw DMA Data
 
-- Packed complex samples
+* Packed complex samples
-- 16-bit real + 16-bit imag per sample
+* 16-bit real + 16-bit imag per sample
-- 4 samples per 128-bit word
+* 4 samples per 128-bit word
 
 ---
 
@@ -64,19 +75,135 @@ Configuration:
 
 Data is unpacked and reshaped into:
 
-```
+```text
 [FrameSize x nFrames x nTriggers]
 ```
 
+or, for processing purposes,
+
+```text
+[FrameSize x nFrames]
+```
+
+representing a single DPW.
+
 ---
 
 ## Processing Pipeline (Current)
 
+```text
 DMA
-→ Unpack samples (I/Q separation)  
+    ↓
-→ Convert to complex representation  
+Unpack samples (I/Q separation)
-→ Reshape into 3D structure  
+    ↓
-→ Visualization / basic analysis  
+Convert to complex representation
+    ↓
+Reshape into DPW matrix
+    ↓
+Processing Path Selection
+
+    Path A:
+        Polyphase Filter Bank (PFB)
+            ↓
+        Power Spectrum
+
+    Path B:
+        FFT
+            ↓
+        Power Spectrum
+
+    Path C:
+        FrFT
+            ↓
+        Mean Power Spectrum
+
+    ↓
+Visualization / Analysis
+```
+
+---
+
+## FrFT Processing Status
+
+A first FrFT processing implementation has been integrated into the PS subsystem.
+
+### Processing Flow
+
+```text
+DPW [512 x nFrames]
+        ↓
+Halfband Interpolation (2x)
+        ↓
+FrFT Coefficient Generation
+        ↓
+DPW-Aware FrFT Processing
+        ↓
+Mean Power Spectrum
+```
+
+### Software Structure
+
+```text
+codegen_fracFdpw/
+│
+├── fracF_init.m
+├── fracF_dpw.m
+├── TBc_fracFdpw.m
+└── TBm_fracFdpw.slx
+```
+
+### Validation Completed
+
+* DPW-aware FrFT implementation created
+* Verified against original `fracF_cg`
+* Bit-identical equivalence achieved
+* MATLAB testbench (TBc) created
+* Simulink model testbench (TBm) created
+* TBc ↔ TBm comparison automated
+* Bit-identical TBc ↔ TBm validation achieved
+* Standalone subsystem code generation validated
+* RFSoC PS integration completed
+
+### Current Status
+
+The implementation is functionally correct and integrated into the RFSoC processing chain.
+
+Current work is focused on:
+
+* Performance characterization
+* FrFT parameter optimization
+* Realistic pulse processing scenarios
+
+### Open Technical Questions
+
+The matched-order formulation used in the SPL simulations assumed:
+
+```text
+Observation Window = Pulse Duration
+```
+
+The receiver currently operates under a different condition:
+
+```text
+Observation Window < Pulse Duration
+```
+
+where only a portion of the pulse is processed by the FrFT.
+
+Additional investigation is required to determine:
+
+* Optimal FrFT order for partial-pulse observations
+* Practical DPW sizes
+* Trade-off between concentration and processing load
+* Deviation from idealized SPL simulation conditions
+
+### Current Limitations
+
+* Coefficients are regenerated every execution
+* No coefficient caching implemented
+* No NEON-specific optimization
+* Generated FFT kernels are used
+* Performance scales strongly with DPW size
 
 ---
 
@@ -84,30 +211,43 @@ DMA
 
 Uses counter-based validation:
 
-- Real part → sample counter
+* Real part → sample counter
-- Imag part → frame index
+* Imag part → frame index
 
 Enables verification of:
 
-- Data continuity
+* Data continuity
-- Frame alignment
+* Frame alignment
-- Correct ordering from DMA
+* Correct ordering from DMA
 
 ---
 
 ## Execution Model
 
-- Triggered (event-based)
+* Triggered (event-based)
-- Burst capture (DPW)
+* Burst capture (DPW)
-- Not continuous real-time streaming
+* Not continuous real-time streaming
 
 ---
 
 ## Performance Notes
 
-- Designed for correctness and validation (not optimized)
+Current implementation prioritizes correctness and validation over optimization.
-- Bottleneck: unpacking + data movement
+
-- Full-rate continuous processing not supported
+Observations from RFSoC integration:
+
+* FrFT processing successfully executes on the RFSoC PS
+* nFrames = 64 executes responsively
+* nFrames = 1024 remains computationally expensive
+* Processing load scales approximately linearly with DPW size
+* Code generation and subsystem integration have been validated
+
+Current optimization candidates:
+
+* Coefficient caching when FrFT order remains unchanged
+* NEON vectorization
+* Alternative FFT implementations
+* DPW size optimization
 
 ---
 
@@ -115,26 +255,40 @@ Enables verification of:
 
 The PS currently serves as:
 
-- Control interface
+* Control interface
-- Data acquisition manager
+* Data acquisition manager
-- Pre-processing stage
+* Signal processing platform
+* Algorithm development and validation environment
 
-Future implementations will replace the current processing with advanced algorithms (e.g., FrFT).
+Current processing capabilities include:
+
+* PFB-based spectral analysis
+* FFT-based spectral analysis
+* FrFT-based spectral analysis
 
 ---
 
 ## Future Work
 
-- FrFT-based processing
+### FrFT
-- Timestamp integration
+
-- UDP streaming
+* Matched-order optimization for realistic pulse captures
-- Optimization (NEON / vectorization)
+* Performance profiling on RFSoC PS
-- Metadata extraction (move complexity to PL)
+* Coefficient caching
+* NEON optimization
+* Detection processing after FrFT concentration
+
+### System
+
+* Timestamp integration
+* UDP streaming
+* Metadata extraction
+* Migration of computationally intensive functions to PL where appropriate
 
 ---
 
 ## 🔗 Related Components
 
-- [🏠 Project Home](../README.md)
+* [🏠 Project Home](../README.md)
-- [PL Tx Subsystem](pl_tx_subsystem.md)
+* [PL Tx Subsystem](pl_tx_subsystem.md)
-- [PL Rx Subsystem](pl_rx_subsystem.md)
+* [PL Rx Subsystem](pl_rx_subsystem.md)