docs: Comprehensive MTL validation framework documentation improvements

- Add interactive paths and clear directory requirements for all commands
- Create validation_quickstart.md for rapid setup with step-by-step guide
- Enhance validation_framework.md with root user requirements and device options
- Add gen_frames.sh usage documentation with supported formats
- Include specific test parameter examples and VF creation instructions
- Update tests/validation/README.md with clickable config file links
- Add comprehensive troubleshooting and multiple device specification methods
- Improve documentation hierarchy following repository standards

Addresses developer feedback for clearer setup instructions and eliminates
common configuration issues that block new developers.

Author: KarolinaPomian

.gitignore

@@ -108,3 +108,5 @@ tools/readpcap/readpcap_*
 swig
 openh264
 level-zero-*
+
+venv*

doc/validation_framework.md

@@ -2,6 +2,8 @@
 
 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)
+
 ## Overview
 
 The validation framework uses pytest to organize and execute tests across various scenarios, protocols, and backend implementations. It supports both automated testing in CI/CD environments and manual testing for development and troubleshooting.
@@ -32,13 +34,37 @@ The `common/` directory contains shared utilities that provide fundamental funct
 - **Integrity Tools**: Provides functions for data integrity verification between source and received media
 - **Network Interface Control**: Manages network interfaces required for testing
 
+#### gen_frames.sh
+
+A shell script for generating test frames for video testing:
+
+- Creates test patterns in various formats
+- Supports different resolutions and frame rates  
+- Configurable color patterns and test signals
+
+**Usage**:
+```bash
+cd tests/validation/common
+./gen_frames.sh
+```
+
+**Supported Formats**:
+- Resolutions: 3840x2160, 1920x1080, 1280x720, 640x360
+- Pixel formats: yuv422p, yuv422p10le
+- Custom color patterns and test signals with timestamps
+- Configurable frame rates and durations
+
 ### Configuration Files
 
 The `configs/` directory contains YAML files that specify:
 
 - **Test Environment Settings**: Hardware specifications, media paths, and test parameters
 - **Network Topology**: Interface configuration, IP addressing, and routing information
 
+#### [test_config.yaml](../tests/validation/configs/test_config.yaml)
+
+Defines the test execution environment:
+
 ### MTL Engine
 
 The `mtl_engine/` directory contains the core components of the framework:
@@ -106,20 +132,26 @@ For complete build instructions, see [doc/build.md](build.md).
 
 ### Environment Setup
 
-1. Create and activate a virtual environment:
+> **⚠️ IMPORTANT**: Run all commands in the `tests/validation/` directory
+
+1. Create and activate a Python virtual environment:
 
 ```bash
-cd tests/validation
+cd tests/validation  # Must be in this directory!
 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 dependencies:
+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:
@@ -131,7 +163,7 @@ python -m pytest --version
 
 #### Critical Configuration Steps
 
-1. **Update `configs/topology_config.yaml`** with your actual network interface details:
+1. **Update [`configs/topology_config.yaml`](../tests/validation/configs/topology_config.yaml)** with your actual network interface details:
 
 ```yaml
 ---
@@ -149,14 +181,25 @@ hosts:
         connection_type: SSHConnection
         connection_options:
           port: 22
-          username: root         # Update with your username
+          username: root         # ⚠️ MUST be root for MTL validation
           password: None         # Use key-based auth when possible
-          key_path: /home/user/.ssh/id_rsa  # Update path to your SSH key
+          key_path: /root/.ssh/id_rsa  # Update path to your SSH key
 ```
 
-**To find your PCI device ID**: `lspci | grep Ethernet`
+**Device Specification Options**:
+- **PCI device ID** (recommended): Find with `lspci | grep Ethernet` → use format like "0000:18:00.0"
+- **System interface name**: Find with `ip link show` → use format like "enp24s0f0"
+
+**To find your options**:
+```bash
+# Find PCI device IDs
+lspci | grep Ethernet
+
+# Find system interface names  
+ip link show
+```
 
-2. **Update `configs/test_config.yaml`** with your environment paths:
+2. **Update [`configs/test_config.yaml`](../tests/validation/configs/test_config.yaml)** with your environment paths:
 
 ```yaml
 build: /path/to/Media-Transport-Library/     # Update to your MTL root directory
@@ -182,14 +225,35 @@ ramdisk:
 - Set `media_path` to where your test media files are located
 - Ensure the paths exist and are accessible
 
+#### Optional: Create VFs for Advanced Testing
+
+For NIC testing with Virtual Functions:
+
+```bash
+# First, identify your network devices
+lspci | grep Ethernet
+
+# Create VFs (replace with your actual PCI device IDs or interface names)
+sudo ./script/nicctl.sh create_vf "0000:18:00.0"  # Replace with your primary port
+sudo ./script/nicctl.sh create_vf "0000:18:00.1"  # Replace with your secondary port
+```
+
+**Examples of valid identifiers**:
+- PCI device ID: `"0000:18:00.0"`
+- Interface name: `"enp24s0f0"`
+- Environment variables: `"${TEST_PF_PORT_P}"` (if you set them)
+
 ## Running Tests
 
-### Basic Usage
+> **⚠️ CRITICAL**: Tests must be run as **root user**, not regular user. MTL validation framework requires root privileges for network operations.
+
+### Basic Test Execution
 
 Run all tests:
 
 ```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
 ```
 
@@ -199,6 +263,18 @@ Run smoke tests:
 python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml -m smoke
 ```
 
+### Running Specific Tests with Parameters
+
+Run a specific test case with custom 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]"
+```
+
+```bash
+python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml -m smoke
+```
+
 Run specific test modules:
 
 ```bash

doc/validation_quickstart.md

@@ -0,0 +1,99 @@
+# MTL Validation Framework - Quick Start Guide
+
+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!)
+
+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)
+
+2. **📋 Basic Requirements**:
+   - Python 3.9+
+   - Root user access (MTL validation requires root privileges)
+   - Network interfaces configured for testing
+
+## Quick Setup (3 steps)
+
+### 1. Install Dependencies
+**Run in tests/validation directory**:
+```bash
+cd tests/validation
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt  # Main framework requirements
+pip install -r common/integrity/requirements.txt  # Integrity test components
+```
+
+### 2. Configure Environment
+Update two key files:
+
+**[tests/validation/configs/topology_config.yaml](../tests/validation/configs/topology_config.yaml)**:
+```yaml
+# Key settings to update:
+username: root  # Must be root for MTL operations
+key_path: /root/.ssh/id_rsa  # Your SSH key path
+```
+
+**[tests/validation/configs/test_config.yaml](../tests/validation/configs/test_config.yaml)**:
+```yaml
+# Replace MTL_PATH_PLACEHOLDER with your actual paths:
+build: /home/gta/Media-Transport-Library/
+mtl_path: /home/gta/Media-Transport-Library/
+```
+
+### 3. Run Tests
+**Basic smoke test**:
+```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
+```
+
+**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]"
+```
+
+## Optional: Create VFs for Advanced Testing
+
+If you need VFs for NIC testing:
+```bash
+# Find your network device first
+lspci | grep Ethernet
+
+# Create VFs (replace with your device identifier)
+sudo ./script/nicctl.sh create_vf ${TEST_PF_PORT_P}
+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) |
+| `Config path errors` | Update placeholder paths in config files |
+
+## Generate Test Media (Optional)
+
+For video testing, generate test frames:
+```bash
+cd tests/validation/common
+./gen_frames.sh
+```
+
+The script supports:
+- Multiple resolutions (3840x2160, 1920x1080, 1280x720, 640x360)
+- Different pixel formats (yuv422p, yuv422p10le)
+- Configurable color patterns and test signals
+- Various frame rates
+
+---
+
+**Need more details?** → [Complete Documentation](validation_framework.md)  
+**Build issues?** → [Build Guide](build.md)  
+**Configuration help?** → [Configuration Guide](configuration_guide.md)

tests/validation/README.md

@@ -2,17 +2,19 @@
 
 The Media Transport Library (MTL) Validation Framework provides comprehensive testing capabilities for various aspects of the MTL, including protocol compliance, performance, and integration testing.
 
-> **For detailed documentation, please refer to [the main validation framework documentation](/doc/validation_framework.md)**
+> **📖 For detailed documentation, please refer to [the main validation framework documentation](../../doc/validation_framework.md)**
+> 
+> **🚀 Quick Start**: See [Validation Quick Start Guide](../../doc/validation_quickstart.md)
 
-## Quick Start Guide
+## Quick Setup
 
 ### Prerequisites
 
 - Python 3.9 or higher
 - **⚠️ CRITICAL**: Media Transport Library built and installed (see [build instructions](../../doc/build.md))
 - Test media files (typically on NFS)
 - Network interfaces configured for testing
-- Root privileges for network operations
+- **Root privileges required** (MTL validation must run as root user)
 - FFmpeg and GStreamer plugins (for integration tests)
 
 ### Setup in 3 Simple Steps
@@ -24,27 +26,32 @@ The Media Transport Library (MTL) Validation Framework provides comprehensive te
    ```
    See [detailed build instructions](../../doc/build.md) if needed.
 
-2. **Create a virtual environment and install dependencies**:
+2. **Create virtual environment and install dependencies** (run in `tests/validation/`):
    ```bash
-   cd tests/validation
+   cd tests/validation  # Must be in this directory!
    python3 -m venv venv
    source venv/bin/activate
-   pip install -r requirements.txt
+   pip install -r requirements.txt  # Main framework requirements
+   pip install -r common/integrity/requirements.txt  # Integrity test components
    ```
 
 3. **Configure your environment**:
-   - Update network interfaces in `configs/topology_config.yaml`
-   - Set correct paths in `configs/test_config.yaml` (especially `build` and `mtl_path`)
+   - Update network interfaces in [`configs/topology_config.yaml`](configs/topology_config.yaml)
+   - Set correct paths in [`configs/test_config.yaml`](configs/test_config.yaml) (especially `build` and `mtl_path`)
    - Ensure media files are accessible at `media_path`
+   - **Use root user** in topology_config.yaml (not regular user)
 
 4. **Run tests**:
    ```bash
-   # Run smoke tests (quick validation)
+   # Run smoke tests (quick validation) - MUST be run as root
    python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml -m smoke
 
    # Run specific test module
    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 with parameters
+   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]"
+   
    # Generate HTML report
    python3 -m pytest --topology_config=configs/topology_config.yaml --test_config=configs/test_config.yaml -m smoke --template=html/index.html --report=report.html
    ```