detailed subsystems

docs/pl_rx_subsystem.md

@@ -1,35 +1,82 @@
 # 📡 PL Rx Subsystem (Channelizer)
 
+[🏠 Project Home](../README.md)
+
+---
+
 ## Overview
 
-Implements PFB channelizer and FFT processing.
+The Rx subsystem implements a **polyphase filter bank (PFB) channelizer** followed by FFT processing.
+
+It converts wideband ADC input into frequency-domain channels.
 
 ---
 
 ## Architecture
 
-ADC → PFB → FFT → Capture → FIFO → AXI → DMA
+ADC
+ ↓
+PFB Channelizer (Decimation + Filtering)
+ ↓
+FFT (512 bins)
+ ↓
+FFT Capture
+ ↓
+FIFO Serializer (4 → 1)
+ ↓
+AXI4-Stream
+ ↓
+DMA
 
 ---
 
-## Processing
+## Processing Chain
 
-- 4096 MSPS input
+### ADC Input
-- Decimation 8
+- Sampling rate: 4096 MSPS
-- FFT 512 bins
+
+### PFB Channelizer
+- Decimation: 8
+- Effective bandwidth: 512 MHz
+
+### FFT
+- Size: 512
+- Produces frequency bins
+
+### FFT Capture
+- Controls frame boundaries
+
+### FIFO Serializer
+- Converts parallel streams into single stream
 
 ---
 
-## Output
+## AXI4-Stream Output
 
-- AXI4-Stream
+- Data type: uint64
-- uint64 format
+- Packed real/imag
-- TLAST per frame
+- TLAST = frame boundary
+
+---
+
+## Data Format
+
+- Frame size: 512 samples
+- Complex values packed into uint64
+
+---
+
+## Key Characteristics
+
+- Fully streaming pipeline
+- High throughput
+- Deterministic latency
+- DMA-ready output
 
 ---
 
 ## 🔗 Related Components
 
-- [Project Overview (README)](../README.md)
+- [🏠 Project Home](../README.md)
 - [PL Tx Subsystem](pl_tx_subsystem.md)
 - [PS Subsystem](ps_subsystem.md)

docs/pl_tx_subsystem.md

@@ -1,50 +1,108 @@
 # 📡 PL Tx Subsystem (Pulse Generator)
 
+[🏠 Project Home](../README.md)
+
+---
+
 ## Overview
 
-The Tx subsystem implements a pulse-based LFM chirp generator using a DDS/NCO architecture.
+The Tx subsystem implements a **pulse-based Linear Frequency Modulated (LFM) chirp generator** using a DDS/NCO architecture in the FPGA (PL).
+
+The generator produces **complex baseband output**:
+
+x[n] = exp(j·φ[n])
+
+and operates deterministically in the PL after a trigger from the PS.
 
 ---
 
 ## Architecture
 
-TxPulseStart → pulse_gen_ctrl → tx_active → NCO → Output
+TxPulseStart (PS)
+        ↓
+pulse_gen_ctrl (FSM)
+        ↓
+   tx_active
+        ↓
+Phase Increment Counter
+        ↓
+      NCO (DDS)
+        ↓
+   Complex Output (I/Q)
 
 ---
 
-## Chirp Generation
+## Chirp Generation Principle
+
+The chirp is generated using a second-order phase accumulator:
 
 Δφ[n] = Δφ[n−1] + step  
 φ[n]  = φ[n−1] + Δφ[n]
 
+This results in a linear frequency sweep.
+
 ---
 
-## Parameterization
+## Parameterization (PS → PL)
 
-- Fc (center frequency)
+Inputs:
-- B (bandwidth)
+
+- Center frequency: Fc  
+- Bandwidth: B  
+- Pulse width: N (samples)
+
+Derived internally:
 
-Derived:
 f_start = Fc − B/2  
 step    = B / (N − 1)
 
+These values are converted to DDS phase increments before being written to PL registers.
+
 ---
 
-## Pulse Timing
+## Pulse Timing (FSM)
+
+States:
+
+- IDLE: waits for trigger and latches parameters  
+- ACTIVE: generates pulses  
+- DONE: waits for trigger reset  
+
+---
+
+## Timing Behavior
+
+Within each PRI:
 
 |<------ PRI ------>|
 |<-- pulse -->| idle |
 
+- tx_active = 1 → chirp output  
+- tx_active = 0 → output zero  
+
+Chirp is reset at each pulse start.
+
 ---
 
-## Trigger
+## Burst Trigger (PS Interaction)
 
-Controlled via TxPulseStart (from PS subsystem)
+- Controlled via TxPulseStart (memory-mapped register)
+- Rising edge triggers burst
+- PL runs autonomously afterward
+
+---
+
+## Key Characteristics
+
+- Deterministic timing (128 MHz)
+- Efficient DDS (adder-based)
+- Complex output (I/Q)
+- Supports burst-mode radar operation
 
 ---
 
 ## 🔗 Related Components
 
-- [Project Overview (README)](../README.md)
+- [🏠 Project Home](../README.md)
-- [PS Subsystem](ps_subsystem.md)
 - [PL Rx Subsystem](pl_rx_subsystem.md)
+- [PS Subsystem](ps_subsystem.md)

docs/ps_subsystem.md

@@ -1,33 +1,85 @@
-# 🧠 PS Subsystem
+# 🧠 PS Subsystem (Control + Processing)
+
+[🏠 Project Home](../README.md)
+
+---
 
 ## Overview
 
-Handles control and processing.
+The PS subsystem is responsible for:
+
+- Configuring PL subsystems
+- Receiving data via DMA
+- Performing frame-based processing
 
 ---
 
-## Control
+## Responsibilities
 
-- Writes parameters
+### Control
-- Triggers Tx (TxPulseStart)
+
+- Writes parameters to PL registers:
+  - Tx generator configuration
+- Generates TxPulseStart trigger
 
 ---
 
-## Processing
+### DMA Handling
 
-DMA → unpack → complex → RMS/peak
+- AXI4-Stream → DMA (S2MM)
+- Data stored in PS DDR
+
+Configuration:
+- Frame size: 512
+- Buffers: 16
 
 ---
 
-## Execution
+### Processing Pipeline
 
-- Event-driven
+DMA → uint64[512]  
-- Frame drops possible
+→ unpack real/imag  
+→ convert to complex  
+→ RMS + peak detection  
+
+---
+
+## Execution Model
+
+- Event-driven (DMA trigger)
+- No buffering queue
+- Frames may be dropped
+
+---
+
+## Performance Notes
+
+- Bottleneck: unpacking + conversion
+- Cannot sustain full-rate input
+
+---
+
+## Interaction with PL
+
+### Tx Control
+- Low-rate trigger (~Hz)
+- Starts burst generation
+
+### Rx Data
+- Continuous high-rate stream
+
+---
+
+## Future Work
+
+- Replace processing with FrFT
+- NEON optimization
+- Throughput improvements
 
 ---
 
 ## 🔗 Related Components
 
-- [Project Overview (README)](../README.md)
+- [🏠 Project Home](../README.md)
 - [PL Tx Subsystem](pl_tx_subsystem.md)
 - [PL Rx Subsystem](pl_rx_subsystem.md)