docs: update validation framework and quick start guide with RxTxApp build instructions and troubleshooting tips

Author: KarolinaPomian

doc/validation_framework.md

@@ -2,7 +2,13 @@
 
 The Media Transport Library (MTL) Validation Framework provides comprehensive testing capabilities for various aspects of the MTL, including protocol compliance, performance, and integration testing.
 
-> **🚀 Quick Start**: For rapid setup, see [Validation Quick Start Guide](validation_quickstart.md)
+## Documentation Navigation
+
+🚀 **Quick Setup**: [Validation Quick Start Guide](validation_quickstart.md) - Get running in 3 steps  
+📁 **Local README**: [tests/validation/README.md](../tests/validation/README.md) - Quick reference and test categories  
+🔧 **Build Guide**: [build.md](build.md) - MTL build instructions  
+
+---
 
 ## Overview
 
@@ -39,13 +45,31 @@ A shell script for generating test frames for video testing:
 - Configurable color patterns and test signals
 - Generates files like `ParkJoy_1080p.yuv`, test patterns, and various resolution formats
 
+**Prerequisites**: Requires FFmpeg with text filters enabled.
+
 **Usage**:
 ```bash
 cd tests/validation/common  # Must be in this directory
 ./gen_frames.sh  # Generates test media files for validation
 # Generated files will be available for test configuration
 ```
 
+**Troubleshooting**: If you get "No such filter: 'drawtext'" errors, install a complete FFmpeg build or skip media generation.
+
+#### RxTxApp Test Tool
+
+**CRITICAL**: Tests require the RxTxApp tool which is not built by the main MTL build process.
+
+**Build Instructions** (required before running tests):
+```bash
+cd tests/tools/RxTxApp
+meson setup build
+meson compile -C build
+cd ../../..
+```
+
+**Location**: After building, RxTxApp is available at `tests/tools/RxTxApp/build/RxTxApp`
+
 **Supported Formats**:
 - Resolutions: 3840x2160, 1920x1080, 1280x720, 640x360
 - Pixel formats: yuv422p, yuv422p10le
@@ -133,8 +157,23 @@ cd ..
 # 3. Build MTL
 cd Media-Transport-Library
 ./build.sh
+
+# 4. Install MTL system-wide (REQUIRED for RxTxApp)
+sudo ninja install -C build
+sudo ldconfig
+
+# 5. Build required test tools (CRITICAL for validation)
+cd tests/tools/RxTxApp
+meson setup build
+meson compile -C build
+cd ../../..
 ```
 
+> **⚠️ CRITICAL**:
+> - The RxTxApp tool is required for validation tests but not built by the main build process
+> - RxTxApp requires MTL to be installed system-wide to build successfully
+> - You must build it separately after installing MTL
+
 For complete build instructions, see [doc/build.md](build.md).
 
 #### 2. Other Prerequisites
@@ -147,33 +186,20 @@ For complete build instructions, see [doc/build.md](build.md).
 
 ### Environment Setup
 
-> **⚠️ IMPORTANT**: Run all commands in the `tests/validation/` directory
+> **🚀 Quick Setup**: See [Validation Quick Start Guide](validation_quickstart.md) for streamlined setup steps.
+
+For detailed setup:
 
-1. Create and activate a Python virtual environment:
+1. Create Python virtual environment in `tests/validation/`:
 
 ```bash
-cd tests/validation  # Must be in this directory!
+cd tests/validation
 python3 -m venv venv
 source venv/bin/activate
-```
-
-**Note**: If you're using VS Code or other development tools that auto-configure Python environments, ensure you're using the correct Python interpreter. The tests require the packages from `tests/validation/requirements.txt`.
-
-2. Install required dependencies:
-
-```bash
-# Main framework requirements (run in tests/validation/)
 pip install -r requirements.txt
-
-# Additional integrity test components (optional but recommended)
 pip install -r common/integrity/requirements.txt
 ```
 
-Verify installation:
-```bash
-python -m pytest --version
-```
-
 ### Configuration
 
 #### Critical Configuration Steps
@@ -265,8 +291,6 @@ sudo ./script/nicctl.sh create_vf "0000:18:00.1"  # Replace with your secondary
 
 > **⚠️ CRITICAL**: Tests must be run as **root user**, not regular user. MTL validation framework requires root privileges for network operations.### Basic Test Execution
 
-**⚠️ CRITICAL**: All tests must be run as **root user**. Regular users will fail.
-
 ### Run specific test with parameters
 
 **Examples of running tests with specific parameters**:
@@ -284,19 +308,9 @@ pytest --topology_config=configs/topology_config.yaml --test_config=configs/test
 pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml "tests/dual/st30p/st30p_format/test_st30p_format.py::test_st30p_format[pcm24]"
 ```
 
-Run all tests:
+> **🚀 Quick Test Execution**: See [Quick Start Guide](validation_quickstart.md#3-run-tests) for basic test commands.
 
-```bash
-cd tests/validation
-source venv/bin/activate  # Activate virtual environment
-python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml
-```
-
-Run smoke tests:
-
-```bash
-python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml -m smoke
-```
+For comprehensive test execution:
 
 ### Running Specific Tests with Parameters
 
@@ -313,13 +327,13 @@ python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=c
 Run specific test modules:
 
 ```bash
-python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml tests/single/st20p/test_st20p_rx.py
+sudo ./venv/bin/python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml tests/single/st20p/test_st20p_rx.py
 ```
 
 Run specific test cases with parameters:
 
 ```bash
-python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml "tests/single/st20p/fps/test_fps.py::test_fps[|fps = p60|-ParkJoy_1080p]"
+sudo ./venv/bin/python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml "tests/single/st20p/fps/test_fps.py::test_fps[|fps = p60|-ParkJoy_1080p]"
 ```
 
 ### Test Categories
@@ -429,6 +443,58 @@ pip install -r requirements.txt
 **Problem**: Network operation failures
 **Solution**: Many tests require root privileges for network operations. Run with appropriate sudo permissions.
 
+#### Build and Setup Issues
+
+**Problem**: `RxTxApp: command not found`
+**Solution**: Build the RxTxApp test tool separately:
+```bash
+cd tests/tools/RxTxApp
+meson setup build
+meson compile -C build
+cd ../../..
+```
+
+**Problem**: RxTxApp build fails with "ST20P_TX_FLAG_EXACT_USER_PACING undeclared" or other header errors
+**Solution**: Install MTL system-wide before building RxTxApp:
+```bash
+cd /path/to/Media-Transport-Library
+sudo ninja install -C build
+sudo ldconfig
+# Then build RxTxApp
+cd tests/tools/RxTxApp
+rm -rf build  # Clean previous failed build
+meson setup build
+meson compile -C build
+```
+
+**Problem**: `No module named pytest` when using sudo
+**Solution**: Use the virtual environment python with sudo:
+```bash
+# Wrong: sudo python3 -m pytest
+# Correct: 
+sudo ./venv/bin/python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml
+```
+
+**Problem**: DSA SSH key errors: `ValueError: q must be exactly 160, 224, or 256 bits long`
+**Solution**: Generate new RSA SSH keys and configure SSH access:
+```bash
+# Generate RSA keys (as your regular user, not root)
+ssh-keygen -t rsa -b 2048 -f ~/.ssh/id_rsa
+
+# Set up SSH access for root@localhost
+ssh-copy-id -i ~/.ssh/id_rsa.pub root@localhost
+
+# Update topology_config.yaml to use your user's key path:
+# key_path: /home/your-username/.ssh/id_rsa  (not /root/.ssh/id_rsa)
+```
+
+**Problem**: FFmpeg `No such filter: 'drawtext'` when running gen_frames.sh
+**Solution**: Install complete FFmpeg build or skip media generation:
+```bash
+sudo apt install ffmpeg  # Full installation
+# Or skip: some tests may work without generated media
+```
+
 #### Media File Access
 **Problem**: Media files not found
 **Solution**: Verify that test media files are available and accessible at the path specified in `media_path`
@@ -437,6 +503,26 @@ pip install -r requirements.txt
 **Problem**: Tests timing out on slower systems
 **Solution**: Increase timeout values in test_config.yaml for slower systems
 
+### Quick Reference Tables
+
+#### Build Issues
+
+| Problem | Solution |
+|---------|----------|
+| `RxTxApp: command not found` | Build RxTxApp: `cd tests/tools/RxTxApp && meson setup build && meson compile -C build` |
+| `MTL library not found` | Install MTL system-wide: `sudo ninja install -C build && sudo ldconfig` |
+| `DSA key error: q must be exactly 160, 224, or 256 bits` | Generate RSA keys: `ssh-keygen -t rsa -b 2048 -f ~/.ssh/id_rsa` |
+
+#### Runtime Issues
+
+| Problem | Solution |
+|---------|----------|
+| `Permission denied` | Use root user: `sudo ./venv/bin/python3 -m pytest` |
+| `No module named pytest` | Don't use `sudo python3`, use `sudo ./venv/bin/python3` |
+| `Config path errors` | Update placeholder paths in config files |
+| `SSH connection failed` | Ensure SSH keys are set up for root@localhost access |
+| `No such filter: 'drawtext'` | Install FFmpeg with text filters or skip media generation |
+
 ### Debugging Tests
 
 Use pytest's debug features:

doc/validation_quickstart.md

@@ -2,19 +2,17 @@
 
 This quick start guide helps you get the MTL validation framework running with minimal setup. For detailed information, see the [complete validation framework documentation](validation_framework.md).
 
-## Prerequisites (Must Complete First!)
+## Prerequisites
 
-1. **🏗️ Build MTL** (CRITICAL - tests will fail without this):
-   ```bash
-   cd /path/to/Media-Transport-Library
-   ./build.sh
-   ```
-   > If this fails, see [detailed build instructions](build.md)
+1. **🏗️ MTL Build Complete**: MTL must be built and test tools available  
+   👉 **[Follow complete build instructions](validation_framework.md#setup-and-installation)**
 
 2. **📋 Basic Requirements**:
    - Python 3.9+
    - Root user access (MTL validation requires root privileges)
    - Network interfaces configured for testing
+   - FFmpeg with text filters (for media generation)
+   - Compatible SSH keys (RSA recommended, not DSA)
 
 ## Quick Setup (3 steps)
 
@@ -35,9 +33,19 @@ Update two key files:
 ```yaml
 # Key settings to update:
 username: root  # Must be root for MTL operations
-key_path: /root/.ssh/id_rsa  # Your SSH key path
+key_path: /home/your-username/.ssh/id_rsa  # YOUR user's SSH key path (not /root/)
+ip_address: 127.0.0.1  # For localhost testing
+port: 22  # Standard SSH port
 ```
 
+> **⚠️ SSH Key Setup**:
+> - Use your regular user's SSH keys (e.g., `/home/gta/.ssh/id_rsa`), not root's keys
+> - If you get DSA key errors, generate new RSA keys:
+> ```bash
+> ssh-keygen -t rsa -b 2048 -f ~/.ssh/id_rsa
+> ssh-copy-id -i ~/.ssh/id_rsa.pub root@localhost
+> ```
+
 **[tests/validation/configs/test_config.yaml](../tests/validation/configs/test_config.yaml)**:
 ```yaml
 # Replace MTL_PATH_PLACEHOLDER with your actual paths:
@@ -46,13 +54,15 @@ mtl_path: /home/gta/Media-Transport-Library/
 ```
 
 ### 3. Run Tests
-**Basic smoke test**:
+**Basic smoke test** (must run as root):
 ```bash
 cd tests/validation
-source venv/bin/activate
-python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml -m smoke -v
+# Use full path to venv python with sudo:
+sudo ./venv/bin/python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml -m smoke -v
 ```
 
+> **💡 Root Execution**: Don't use `sudo python3` (uses system python). Use `sudo ./venv/bin/python3` to use the virtual environment.
+
 **Run specific test with parameters**:
 ```bash
 pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml "tests/single/st20p/fps/test_fps.py::test_fps[|fps = p60|-ParkJoy_1080p]"
@@ -72,29 +82,27 @@ sudo ./script/nicctl.sh create_vf ${TEST_PF_PORT_R}
 
 ## Quick Troubleshooting
 
-| Error | Solution |
-|-------|----------|
-| `RxTxApp: command not found` | Build MTL first with `./build.sh` |
-| `Permission denied` | Use root user (not regular user) |
+| Common Error | Quick Solution |
+|--------------|----------------|
+| `RxTxApp: command not found` | [Follow build instructions](validation_framework.md#rxtxapp-test-tool) |
+| `Permission denied` | Use root: `sudo ./venv/bin/python3 -m pytest` |
+| `No module named pytest` | Don't use `sudo python3`, use `sudo ./venv/bin/python3` |
 | `Config path errors` | Update placeholder paths in config files |
+| SSH/FFmpeg issues | See [detailed troubleshooting](validation_framework.md#troubleshooting) |
 
 ## Generate Test Media (Optional)
 
-For video testing, generate test frames (must run from specific directory):
-```bash
-cd tests/validation/common  # Must be in this directory
-./gen_frames.sh             # Generates test media files
-```
-
-The script supports:
-- Multiple resolutions (3840x2160, 1920x1080, 1280x720, 640x360)
-- Different pixel formats (yuv422p, yuv422p10le)
-- Configurable color patterns and test signals with timestamps
-- Various frame rates and durations
-- Generates files like `ParkJoy_1080p.yuv` used in test examples
+For video testing, you may need test media files:  
+👉 **[See media generation instructions](validation_framework.md#gen_framessh)**
 
 ---
 
-**Need more details?** → [Complete Documentation](validation_framework.md)  
-**Build issues?** → [Build Guide](build.md)  
-**Configuration help?** → [Configuration Guide](configuration_guide.md)
+## Documentation Navigation
+
+📖 **Complete Documentation**: [Validation Framework](validation_framework.md) - Detailed information, configuration, and advanced features  
+🔧 **Build Issues**: [Build Guide](build.md) - MTL build instructions  
+⚙️ **Configuration Help**: [Configuration Guide](configuration_guide.md) - Network and environment setup  
+
+## Summary
+
+This quick start guide gets you running tests in minutes. For production use, detailed configuration, or troubleshooting complex issues, refer to the complete documentation above.