docs: update documentation for capture redesign and validation

docs/ps_subsystem.md

@@ -1,4 +1,4 @@
-# 🧠 PS Subsystem (Control + Processing)
+# 🧠 PS Subsystem (Control + Capture + Processing)
 
 [🏠 Project Home](../README.md)
 
@@ -8,73 +8,128 @@
 
 The PS subsystem is responsible for:
 
+- System initialization
 - Configuring PL subsystems
+- Triggering captures
 - Receiving data via DMA
-- Performing frame-based processing
+- Preparing data for processing and visualization
+
+The current implementation acts as a **placeholder for post-processing**, focusing on reliable data acquisition and host interaction.
 
 ---
 
 ## Responsibilities
 
-### Control
+### Control & Initialization
 
-- Writes parameters to PL registers:
-  - Tx generator configuration
-- Generates TxPulseStart trigger
+- Configure PL parameters:
+  - Tx waveform configuration
+  - Capture parameters (nFrames, etc.)
+- Initialize DMA and memory buffers
+- Manage system startup
+
+---
+
+### Trigger & Capture
+
+- Generates capture trigger (software-controlled)
+- Controls DPW acquisition timing
+- Each trigger initiates one DPW capture
 
 ---
 
 ### DMA Handling
 
 - AXI4-Stream → DMA (S2MM)
-- Data stored in PS DDR
+- Receives **128-bit stream** (4 samples per clock)
+- Stores data in PS DDR memory
 
 Configuration:
-- Frame size: 512
-- Buffers: 16
+- Frame size: 512 samples
+- nFrames: configurable (validated up to 1024)
 
 ---
 
-### Processing Pipeline
+## Data Format
 
-DMA → uint64[512]  
-→ unpack real/imag  
-→ convert to complex  
-→ RMS + peak detection  
+### Raw DMA Data
+
+- Packed complex samples
+- 16-bit real + 16-bit imag per sample
+- 4 samples per 128-bit word
+
+---
+
+### Processing Representation
+
+Data is unpacked and reshaped into:
+
+```
+[FrameSize x nFrames x nTriggers]
+```
+
+---
+
+## Processing Pipeline (Current)
+
+DMA  
+→ Unpack samples (I/Q separation)  
+→ Convert to complex representation  
+→ Reshape into 3D structure  
+→ Visualization / basic analysis  
+
+---
+
+## Validation Support
+
+Uses counter-based validation:
+
+- Real part → sample counter
+- Imag part → frame index
+
+Enables verification of:
+
+- Data continuity
+- Frame alignment
+- Correct ordering from DMA
 
 ---
 
 ## Execution Model
 
-- Event-driven (DMA trigger)
-- No buffering queue
-- Frames may be dropped
+- Triggered (event-based)
+- Burst capture (DPW)
+- Not continuous real-time streaming
 
 ---
 
 ## Performance Notes
 
-- Bottleneck: unpacking + conversion
-- Cannot sustain full-rate input
+- Designed for correctness and validation (not optimized)
+- Bottleneck: unpacking + data movement
+- Full-rate continuous processing not supported
 
 ---
 
-## Interaction with PL
+## Role in System
 
-### Tx Control
-- Low-rate trigger (~Hz)
-- Starts burst generation
+The PS currently serves as:
 
-### Rx Data
-- Continuous high-rate stream
+- Control interface
+- Data acquisition manager
+- Pre-processing stage
+
+Future implementations will replace the current processing with advanced algorithms (e.g., FrFT).
 
 ---
 
 ## Future Work
 
-- Replace processing with FrFT
-- NEON optimization
-- Throughput improvements
+- FrFT-based processing
+- Timestamp integration
+- UDP streaming
+- Optimization (NEON / vectorization)
+- Metadata extraction (move complexity to PL)
 
 ---