devtools: add AI-assisted code review tools

new file mode 100755
index 0000000000..cbd106d4dd
@@ -0,0 +1,1509 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2026 Stephen Hemminger
+
+"""
+Analyze DPDK patches using AI providers.
+
+Supported providers: Anthropic Claude, OpenAI ChatGPT, xAI Grok, Google Gemini
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass, field
+from datetime import date
+from email.message import EmailMessage
+from pathlib import Path
+from typing import Any, Iterator, NoReturn
+from urllib.request import Request, urlopen
+from urllib.error import URLError, HTTPError
+
+# Output formats
+OUTPUT_FORMATS = ["text", "markdown", "html", "json"]
+
+# Large file handling modes
+LARGE_FILE_MODES = ["error", "truncate", "chunk", "commits-only", "summary"]
+
+# Approximate characters per token (conservative: fewer chars = higher estimate)
+CHARS_PER_TOKEN = 3.5
+
+# Default token limits by provider (leaving room for system prompt and response)
+PROVIDER_INPUT_LIMITS = {
+    "anthropic": 180000,  # 200K context, reserve for system/response
+    "openai": 900000,  # GPT-4.1 has 1M context
+    "xai": 1800000,  # Grok 4.1 Fast has 2M context
+    "google": 900000,  # Gemini 3 Flash has 1M context
+}
+
+
+@dataclass
+class TokenUsage:
+    """Accumulated token usage across API calls."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_creation_tokens: int = 0
+    cache_read_tokens: int = 0
+    api_calls: int = 0
+
+    def add(self, other: "TokenUsage") -> None:
+        """Accumulate usage from another TokenUsage."""
+        self.input_tokens += other.input_tokens
+        self.output_tokens += other.output_tokens
+        self.cache_creation_tokens += other.cache_creation_tokens
+        self.cache_read_tokens += other.cache_read_tokens
+        self.api_calls += other.api_calls
+
+
+# Pricing per million tokens (USD) - update as prices change.
+# Keys are (provider, model-prefix) tuples; first prefix match wins.
+# "default" key is fallback for unknown models within a provider.
+def format_token_summary(usage: TokenUsage, provider: str, model: str) -> str:
+    """Format a token usage summary string."""
+    lines = ["=== Token Usage Summary ==="]
+    lines.append(f"API calls:     {usage.api_calls}")
+    lines.append(f"Input tokens:  {usage.input_tokens:,}")
+    lines.append(f"Output tokens: {usage.output_tokens:,}")
+    if usage.cache_creation_tokens:
+        lines.append(f"Cache write:   {usage.cache_creation_tokens:,}")
+    if usage.cache_read_tokens:
+        lines.append(f"Cache read:    {usage.cache_read_tokens:,}")
+    total = usage.input_tokens + usage.output_tokens
+    lines.append(f"Total tokens:  {total:,}")
+    lines.append("=" * 27)
+    return "\n".join(lines)
+
+
+# Provider configurations
+PROVIDERS = {
+    "anthropic": {
+        "name": "Claude",
+        "endpoint": "https://api.anthropic.com/v1/messages",
+        "default_model": "claude-sonnet-4-5-20250929",
+        "env_var": "ANTHROPIC_API_KEY",
+    },
+    "openai": {
+        "name": "ChatGPT",
+        "endpoint": "https://api.openai.com/v1/chat/completions",
+        "default_model": "gpt-4.1",
+        "env_var": "OPENAI_API_KEY",
+    },
+    "xai": {
+        "name": "Grok",
+        "endpoint": "https://api.x.ai/v1/chat/completions",
+        "default_model": "grok-4-1-fast-non-reasoning",
+        "env_var": "XAI_API_KEY",
+    },
+    "google": {
+        "name": "Gemini",
+        "endpoint": "https://generativelanguage.googleapis.com/v1beta/models",
+        "default_model": "gemini-3-flash-preview",
+        "env_var": "GOOGLE_API_KEY",
+    },
+}
+
+# LTS releases: any DPDK release with minor version .11
+# (e.g., 19.11, 20.11, 21.11, 22.11, 23.11, 24.11, 25.11, ...)
+
+SYSTEM_PROMPT_BASE = """\
+You are an expert DPDK code reviewer. Analyze patches for compliance with \
+DPDK coding standards and contribution guidelines. Provide clear, actionable \
+feedback organized by severity (Error, Warning, Info) as defined in the \
+guidelines."""
+
+LTS_RULES = """
+LTS (Long Term Stable) branch rules apply:
+- Only bug fixes allowed, no new features
+- No new APIs (experimental or stable)
+- ABI must remain unchanged
+- Backported fixes should reference the original commit with Fixes: tag
+- Copyright years should reflect when the code was originally written
+- Be conservative: reject changes that aren't clearly bug fixes"""
+
+FORMAT_INSTRUCTIONS = {
+    "text": """Provide your review in plain text format.""",
+    "markdown": """Provide your review in Markdown format with:
+- Headers (##) for each severity level (Errors, Warnings, Info)
+- Bullet points for individual issues
+- Code blocks (```) for code references
+- Bold (**) for emphasis on key points""",
+    "html": """Provide your review in HTML format with:
+- <h2> tags for each severity level (Errors, Warnings, Info)
+- <ul>/<li> for individual issues
+- <pre><code> for code references
+- <strong> for emphasis on key points
+- Use appropriate semantic HTML tags
+- Do NOT include <html>, <head>, or <body> tags - just the content""",
+    "json": """Provide your review in JSON format with this structure:
+{
+  "summary": "Brief one-line summary of the review",
+  "errors": [
+    {"issue": "description", "location": "file:line", "suggestion": "fix"}
+  ],
+  "warnings": [
+    {"issue": "description", "location": "file:line", "suggestion": "fix"}
+  ],
+  "info": [
+    {"issue": "description", "location": "file:line", "suggestion": "fix"}
+  ],
+  "passed_checks": ["list of checks that passed"],
+  "overall_status": "PASS|WARN|FAIL"
+}
+Output ONLY valid JSON, no markdown code fences or other text.""",
+}
+
+USER_PROMPT = """Please review the following DPDK patch file '{patch_name}' \
+against the AGENTS.md guidelines. Focus on:
+
+1. Correctness bugs (resource leaks, use-after-free, race conditions, etc.)
+2. C coding style (forbidden tokens, implicit comparisons, unnecessary patterns)
+3. API and documentation requirements
+4. Any other guideline violations
+
+Note: commit message formatting and SPDX/copyright compliance are checked \
+by checkpatches.sh and should NOT be flagged here.
+
+{format_instruction}
+
+--- PATCH CONTENT ---
+"""
+
+
+def error(msg: str) -> NoReturn:
+    """Print error message and exit."""
+    print(f"Error: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+# Exit codes for review results
+EXIT_CLEAN = 0
+EXIT_WARNINGS = 2
+EXIT_ERRORS = 3
+
+
+def classify_review(review_text: str, output_format: str) -> int:
+    """Classify review result and return appropriate exit code.
+
+    Returns:
+        0 - clean (no errors or warnings)
+        2 - warnings found (no errors)
+        3 - errors found
+    """
+    has_errors = False
+    has_warnings = False
+
+    if output_format == "json":
+        try:
+            data = json.loads(review_text)
+            if data.get("errors"):
+                has_errors = True
+            if data.get("warnings"):
+                has_warnings = True
+            status = data.get("overall_status", "").upper()
+            if status == "FAIL":
+                has_errors = True
+            elif status == "WARN":
+                has_warnings = True
+        except (json.JSONDecodeError, AttributeError):
+            pass  # Fall through to text scanning
+
+    if not has_errors and not has_warnings:
+        # Scan review text for severity indicators.
+        # Match section headers and inline markers across text/markdown/html.
+        for line in review_text.splitlines():
+            stripped = line.strip().lower()
+            # Skip quoted patch context lines
+            if stripped.startswith(">") or stripped.startswith("diff --git"):
+                continue
+            if re.match(r"^(#{1,3}\s+)?(\*{0,2})error", stripped) or re.match(
+                r"^<h[1-3]>\s*error", stripped
+            ):
+                has_errors = True
+            elif re.match(r"^(#{1,3}\s+)?(\*{0,2})warning", stripped) or re.match(
+                r"^<h[1-3]>\s*warning", stripped
+            ):
+                has_warnings = True
+
+    if has_errors:
+        return EXIT_ERRORS
+    if has_warnings:
+        return EXIT_WARNINGS
+    return EXIT_CLEAN
+
+
+def get_git_config(key: str) -> str | None:
+    """Get a value from git config."""
+    try:
+        result = subprocess.run(
+            ["git", "config", "--get", key],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+
+def is_lts_release(release: str | None) -> bool:
+    """Check if a release is an LTS release.
+
+    Per DPDK project guidelines, any release with minor version .11
+    is an LTS release (e.g., 19.11, 21.11, 23.11, 24.11, 25.11).
+    """
+    if not release:
+        return False
+    # Check for explicit -lts suffix
+    if "-lts" in release.lower():
+        return True
+    # Extract base version (e.g., "23.11" from "23.11.1" or "23.11-rc1")
+    version = release.split("-")[0]
+    parts = version.split(".")
+    if len(parts) >= 2:
+        try:
+            minor = int(parts[1])
+            return minor == 11
+        except ValueError:
+            pass
+    return False
+
+
+def estimate_tokens(text: str) -> int:
+    """Estimate token count from text length."""
+    return int(len(text) / CHARS_PER_TOKEN)
+
+
+def split_mbox_patches(content: str) -> list[str]:
+    """Split an mbox file into individual patches."""
+    patches = []
+    current_patch = []
+    in_patch = False
+
+    for line in content.split("\n"):
+        # Detect start of new message in mbox format
+        # git-format-patch: "From <40-char-hex> Mon Sep 17 00:00:00 2001"
+        # general mbox: "From <addr> <day-of-week> ..."
+        if line.startswith("From ") and (
+            re.match(r"^From [0-9a-f]{40} ", line)
+            or " Mon " in line
+            or " Tue " in line
+            or " Wed " in line
+            or " Thu " in line
+            or " Fri " in line
+            or " Sat " in line
+            or " Sun " in line
+        ):
+            if current_patch:
+                patches.append("\n".join(current_patch))
+            current_patch = [line]
+            in_patch = True
+        elif in_patch:
+            current_patch.append(line)
+
+    # Don't forget the last patch
+    if current_patch:
+        patches.append("\n".join(current_patch))
+
+    return patches if patches else [content]
+
+
+def extract_commit_messages(content: str) -> str:
+    """Extract only commit messages from patch content."""
+    patches = split_mbox_patches(content)
+    messages = []
+
+    for patch in patches:
+        lines = patch.split("\n")
+        msg_lines = []
+        in_headers = True
+        in_body = False
+        found_subject = False
+
+        for line in lines:
+            # Collect headers we care about
+            if in_headers:
+                if line.startswith("Subject:"):
+                    msg_lines.append(line)
+                    found_subject = True
+                elif line.startswith(("From:", "Date:")):
+                    msg_lines.append(line)
+                elif line.startswith((" ", "\t")) and found_subject:
+                    # Subject continuation
+                    msg_lines.append(line)
+                elif line == "":
+                    if found_subject:
+                        in_headers = False
+                        in_body = True
+                        msg_lines.append("")
+            elif in_body:
+                # Stop at the diffstat separator or diff
+                if line.rstrip() == "---":
+                    break
+                if line.startswith("diff --git"):
+                    break
+                msg_lines.append(line)
+
+        if msg_lines:
+            messages.append("\n".join(msg_lines))
+
+    return "\n\n---\n\n".join(messages)
+
+
+def truncate_content(content: str, max_tokens: float) -> tuple[str, bool]:
+    """Truncate content to fit within token limit."""
+    max_chars = int(max_tokens * CHARS_PER_TOKEN)
+
+    if len(content) <= max_chars:
+        return content, False
+
+    # Try to truncate at a reasonable boundary
+    truncated = content[:max_chars]
+
+    # Find last complete diff hunk or patch boundary
+    last_diff = truncated.rfind("\ndiff --git")
+    last_patch = truncated.rfind("\nFrom ")
+
+    if last_diff > max_chars * 0.5:
+        truncated = truncated[:last_diff]
+    elif last_patch > max_chars * 0.5:
+        truncated = truncated[:last_patch]
+
+    truncated += "\n\n[... Content truncated due to size limits ...]\n"
+    return truncated, True
+
+
+def chunk_content(content: str, max_tokens: int) -> Iterator[tuple[str, int, int]]:
+    """Split content into chunks that fit within token limit.
+
+    Yields tuples of (chunk_content, chunk_number, total_chunks).
+    """
+    patches = split_mbox_patches(content)
+
+    if len(patches) == 1:
+        # Single large patch - split by diff sections
+        yield from chunk_single_patch(content, max_tokens)
+        return
+
+    # Multiple patches - group them to fit within limits
+    chunks = []
+    current_chunk = []
+    current_size = 0
+    max_chars = int(max_tokens * CHARS_PER_TOKEN * 0.9)  # 90% to leave margin
+
+    for patch in patches:
+        patch_size = len(patch)
+        if current_size + patch_size > max_chars and current_chunk:
+            chunks.append("\n".join(current_chunk))
+            current_chunk = []
+            current_size = 0
+
+        if patch_size > max_chars:
+            # Single patch too large, truncate it
+            if current_chunk:
+                chunks.append("\n".join(current_chunk))
+                current_chunk = []
+                current_size = 0
+            truncated, _ = truncate_content(patch, max_tokens * 0.9)
+            chunks.append(truncated)
+        else:
+            current_chunk.append(patch)
+            current_size += patch_size
+
+    if current_chunk:
+        chunks.append("\n".join(current_chunk))
+
+    total = len(chunks)
+    for i, chunk in enumerate(chunks, 1):
+        yield chunk, i, total
+
+
+def chunk_single_patch(content: str, max_tokens: int) -> Iterator[tuple[str, int, int]]:
+    """Split a single large patch by diff sections."""
+    max_chars = int(max_tokens * CHARS_PER_TOKEN * 0.9)
+
+    # Extract header (everything before first diff)
+    first_diff = content.find("\ndiff --git")
+    if first_diff == -1:
+        # No diff sections, just truncate
+        truncated, _ = truncate_content(content, max_tokens * 0.9)
+        yield truncated, 1, 1
+        return
+
+    header = content[: first_diff + 1]
+    diff_content = content[first_diff + 1 :]
+
+    # Split by diff sections
+    diffs = []
+    current_diff = []
+    for line in diff_content.split("\n"):
+        if line.startswith("diff --git") and current_diff:
+            diffs.append("\n".join(current_diff))
+            current_diff = []
+        current_diff.append(line)
+    if current_diff:
+        diffs.append("\n".join(current_diff))
+
+    # Group diffs into chunks
+    chunks = []
+    current_chunk_diffs = []
+    current_size = len(header)
+
+    for diff in diffs:
+        diff_size = len(diff)
+        if current_size + diff_size > max_chars and current_chunk_diffs:
+            chunks.append(header + "\n".join(current_chunk_diffs))
+            current_chunk_diffs = []
+            current_size = len(header)
+
+        if diff_size + len(header) > max_chars:
+            # Single diff too large
+            if current_chunk_diffs:
+                chunks.append(header + "\n".join(current_chunk_diffs))
+                current_chunk_diffs = []
+            truncated_diff = diff[: max_chars - len(header) - 100]
+            truncated_diff += "\n[... diff truncated ...]\n"
+            chunks.append(header + truncated_diff)
+            current_size = len(header)
+        else:
+            current_chunk_diffs.append(diff)
+            current_size += diff_size
+
+    if current_chunk_diffs:
+        chunks.append(header + "\n".join(current_chunk_diffs))
+
+    total = len(chunks)
+    for i, chunk in enumerate(chunks, 1):
+        yield chunk, i, total
+
+
+def get_summary_prompt() -> str:
+    """Get prompt modifications for summary mode."""
+    return """
+NOTE: This is a LARGE patch series. Provide a HIGH-LEVEL summary review only:
+- Focus on overall architecture and design concerns
+- Check commit message formatting across the series
+- Identify any obvious policy violations
+- Do NOT attempt detailed line-by-line code review
+- Summarize the scope and purpose of the changes
+"""
+
+
+def format_combined_reviews(
+    reviews: list[tuple[str, str]], output_format: str, patch_name: str
+) -> str:
+    """Combine multiple chunk/patch reviews into a single output."""
+    if output_format == "json":
+        combined = {
+            "patch_file": patch_name,
+            "sections": [
+                {"label": label, "review": review} for label, review in reviews
+            ],
+        }
+        return json.dumps(combined, indent=2)
+    elif output_format == "html":
+        sections = []
+        for label, review in reviews:
+            sections.append(f"<h2>{label}</h2>\n{review}")
+        return "\n<hr>\n".join(sections)
+    elif output_format == "markdown":
+        sections = []
+        for label, review in reviews:
+            sections.append(f"## {label}\n\n{review}")
+        return "\n\n---\n\n".join(sections)
+    else:  # text
+        sections = []
+        for label, review in reviews:
+            sections.append(f"=== {label} ===\n\n{review}")
+        separator = "\n\n" + "=" * 60 + "\n\n"
+        return separator.join(sections)
+
+
+def build_system_prompt(review_date: str, release: str | None) -> str:
+    """Build system prompt with date and release context."""
+    prompt = SYSTEM_PROMPT_BASE
+    prompt += f"\n\nCurrent date: {review_date}."
+
+    if release:
+        prompt += f"\nTarget DPDK release: {release}."
+        if is_lts_release(release):
+            prompt += LTS_RULES
+        else:
+            prompt += "\nThis is a main branch or standard release."
+            prompt += "\nNew features and experimental APIs are allowed."
+
+    return prompt
+
+
+def build_anthropic_request(
+    model: str,
+    max_tokens: int,
+    system_prompt: str,
+    agents_content: str,
+    patch_content: str,
+    patch_name: str,
+    output_format: str = "text",
+) -> dict[str, Any]:
+    """Build request payload for Anthropic API."""
+    format_instruction = FORMAT_INSTRUCTIONS.get(output_format, "")
+    user_prompt = USER_PROMPT.format(
+        patch_name=patch_name, format_instruction=format_instruction
+    )
+    return {
+        "model": model,
+        "max_tokens": max_tokens,
+        "system": [
+            {"type": "text", "text": system_prompt},
+            {
+                "type": "text",
+                "text": agents_content,
+                "cache_control": {"type": "ephemeral"},
+            },
+        ],
+        "messages": [
+            {
+                "role": "user",
+                "content": user_prompt + patch_content,
+            }
+        ],
+    }
+
+
+def build_openai_request(
+    model: str,
+    max_tokens: int,
+    system_prompt: str,
+    agents_content: str,
+    patch_content: str,
+    patch_name: str,
+    output_format: str = "text",
+) -> dict[str, Any]:
+    """Build request payload for OpenAI-compatible APIs."""
+    format_instruction = FORMAT_INSTRUCTIONS.get(output_format, "")
+    user_prompt = USER_PROMPT.format(
+        patch_name=patch_name, format_instruction=format_instruction
+    )
+    return {
+        "model": model,
+        "max_tokens": max_tokens,
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "system", "content": agents_content},
+            {
+                "role": "user",
+                "content": user_prompt + patch_content,
+            },
+        ],
+    }
+
+
+def build_google_request(
+    max_tokens: int,
+    system_prompt: str,
+    agents_content: str,
+    patch_content: str,
+    patch_name: str,
+    output_format: str = "text",
+) -> dict[str, Any]:
+    """Build request payload for Google Gemini API."""
+    format_instruction = FORMAT_INSTRUCTIONS.get(output_format, "")
+    user_prompt = USER_PROMPT.format(
+        patch_name=patch_name, format_instruction=format_instruction
+    )
+    return {
+        "system_instruction": {
+            "parts": [
+                {"text": system_prompt},
+                {"text": agents_content},
+            ]
+        },
+        "contents": [
+            {
+                "role": "user",
+                "parts": [{"text": user_prompt + patch_content}],
+            },
+        ],
+        "generationConfig": {"maxOutputTokens": max_tokens},
+    }
+
+
+def call_api(
+    provider: str,
+    api_key: str,
+    model: str,
+    max_tokens: int,
+    system_prompt: str,
+    agents_content: str,
+    patch_content: str,
+    patch_name: str,
+    output_format: str = "text",
+    verbose: bool = False,
+    timeout: int = 300,
+) -> tuple[str, TokenUsage]:
+    """Make API request to the specified provider.
+
+    Returns a tuple of (response_text, token_usage).
+    """
+    config = PROVIDERS[provider]
+
+    # Build request based on provider
+    if provider == "anthropic":
+        request_data = build_anthropic_request(
+            model,
+            max_tokens,
+            system_prompt,
+            agents_content,
+            patch_content,
+            patch_name,
+            output_format,
+        )
+        headers = {
+            "Content-Type": "application/json",
+            "x-api-key": api_key,
+            "anthropic-version": "2023-06-01",
+        }
+        url = config["endpoint"]
+    elif provider == "google":
+        request_data = build_google_request(
+            max_tokens,
+            system_prompt,
+            agents_content,
+            patch_content,
+            patch_name,
+            output_format,
+        )
+        headers = {"Content-Type": "application/json"}
+        url = f"{config['endpoint']}/{model}:generateContent?key={api_key}"
+    else:  # openai, xai
+        request_data = build_openai_request(
+            model,
+            max_tokens,
+            system_prompt,
+            agents_content,
+            patch_content,
+            patch_name,
+            output_format,
+        )
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        }
+        url = config["endpoint"]
+
+    # Make request
+    request_body = json.dumps(request_data).encode("utf-8")
+    req = Request(url, data=request_body, headers=headers, method="POST")
+
+    try:
+        with urlopen(req, timeout=timeout) as response:
+            result = json.loads(response.read().decode("utf-8"))
+    except HTTPError as e:
+        error_body = e.read().decode("utf-8")
+        try:
+            error_data = json.loads(error_body)
+            error(f"API error: {error_data.get('error', error_body)}")
+        except json.JSONDecodeError:
+            error(f"API error ({e.code}): {error_body}")
+    except URLError as e:
+        if isinstance(e.reason, TimeoutError):
+            error(f"API request timed out after {timeout} seconds")
+        error(f"Connection error: {e.reason}")
+    except TimeoutError:
+        error(f"API request timed out after {timeout} seconds")
+
+    # Extract token usage
+    usage = TokenUsage(api_calls=1)
+    if provider == "anthropic":
+        raw_usage = result.get("usage", {})
+        usage.input_tokens = raw_usage.get("input_tokens", 0)
+        usage.output_tokens = raw_usage.get("output_tokens", 0)
+        usage.cache_creation_tokens = raw_usage.get("cache_creation_input_tokens", 0)
+        usage.cache_read_tokens = raw_usage.get("cache_read_input_tokens", 0)
+    elif provider == "google":
+        raw_usage = result.get("usageMetadata", {})
+        usage.input_tokens = raw_usage.get("promptTokenCount", 0)
+        usage.output_tokens = raw_usage.get("candidatesTokenCount", 0)
+    else:  # openai, xai
+        raw_usage = result.get("usage", {})
+        usage.input_tokens = raw_usage.get("prompt_tokens", 0)
+        usage.output_tokens = raw_usage.get("completion_tokens", 0)
+        # OpenAI cache details (if available)
+        cache_details = raw_usage.get("prompt_tokens_details", {})
+        if cache_details:
+            usage.cache_read_tokens = cache_details.get("cached_tokens", 0)
+
+    # Show per-call details in verbose mode
+    if verbose:
+        print("=== Token Usage ===", file=sys.stderr)
+        print(f"Input tokens: {usage.input_tokens:,}", file=sys.stderr)
+        print(f"Output tokens: {usage.output_tokens:,}", file=sys.stderr)
+        if usage.cache_creation_tokens:
+            print(
+                f"Cache creation: {usage.cache_creation_tokens:,}",
+                file=sys.stderr,
+            )
+        if usage.cache_read_tokens:
+            print(
+                f"Cache read: {usage.cache_read_tokens:,}",
+                file=sys.stderr,
+            )
+        print("===================", file=sys.stderr)
+
+    # Extract response text
+    if provider == "anthropic":
+        if "error" in result:
+            error(f"API error: {result['error'].get('message', result)}")
+        content = result.get("content", [])
+        text = "".join(
+            block.get("text", "") for block in content if block.get("type") == "text"
+        )
+        return text, usage
+    elif provider == "google":
+        if "error" in result:
+            error(f"API error: {result['error'].get('message', result)}")
+        candidates = result.get("candidates", [])
+        if not candidates:
+            error("No response from Gemini")
+        parts = candidates[0].get("content", {}).get("parts", [])
+        text = "".join(part.get("text", "") for part in parts)
+        return text, usage
+    else:  # openai, xai
+        if "error" in result:
+            error(f"API error: {result['error'].get('message', result)}")
+        choices = result.get("choices", [])
+        if not choices:
+            error("No response from API")
+        text = choices[0].get("message", {}).get("content", "")
+        return text, usage
+
+
+def get_last_message_id(patch_content: str) -> str | None:
+    """Extract Message-ID from the last patch in an mbox."""
+    msg_ids = re.findall(
+        r"^Message-I[Dd]:\s*(.+)$", patch_content, re.MULTILINE | re.IGNORECASE
+    )
+    if msg_ids:
+        msg_id = msg_ids[-1].strip()
+        # Normalize: remove < > and add them back
+        msg_id = msg_id.strip("<>")
+        return f"<{msg_id}>"
+    return None
+
+
+def get_last_subject(patch_content: str) -> str | None:
+    """Extract subject from the last patch in an mbox."""
+    # Find all Subject lines with potential continuations
+    subjects = []
+    lines = patch_content.split("\n")
+    i = 0
+    while i < len(lines):
+        if lines[i].lower().startswith("subject:"):
+            subject = lines[i][8:].strip()
+            i += 1
+            # Handle continuation lines (RFC 2822 folding)
+            while i < len(lines) and lines[i].startswith((" ", "\t")):
+                subject += " " + lines[i].strip()
+                i += 1
+            subjects.append(subject)
+        else:
+            i += 1
+    return subjects[-1] if subjects else None
+
+
+def send_email(
+    to_addrs: list[str],
+    cc_addrs: list[str],
+    from_addr: str,
+    subject: str,
+    in_reply_to: str | None,
+    body: str,
+    dry_run: bool = False,
+) -> bool:
+    """Send review email using git send-email, sendmail, or msmtp."""
+    msg = EmailMessage()
+    msg["From"] = from_addr
+    msg["To"] = ", ".join(to_addrs)
+    if cc_addrs:
+        msg["Cc"] = ", ".join(cc_addrs)
+    msg["Subject"] = subject
+    if in_reply_to:
+        msg["In-Reply-To"] = in_reply_to
+        msg["References"] = in_reply_to
+    msg.set_content(body)
+
+    email_text = msg.as_string()
+
+    if dry_run:
+        print("=== Email Preview (dry-run) ===", file=sys.stderr)
+        print(email_text, file=sys.stderr)
+        print("=== End Preview ===", file=sys.stderr)
+        return True
+
+    # Write to temp file for git send-email
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".eml", delete=False) as f:
+        f.write(email_text)
+        temp_file = f.name
+
+    try:
+        # Try git send-email first
+        if get_git_config("sendemail.smtpserver"):
+            # Build command with all arguments
+            flat_cmd = ["git", "send-email", "--confirm=never", "--quiet"]
+            for addr in to_addrs:
+                flat_cmd.extend(["--to", addr])
+            for addr in cc_addrs:
+                flat_cmd.extend(["--cc", addr])
+            if from_addr:
+                flat_cmd.extend(["--from", from_addr])
+            if in_reply_to:
+                flat_cmd.extend(["--in-reply-to", in_reply_to])
+            flat_cmd.append(temp_file)
+
+            try:
+                subprocess.run(flat_cmd, check=True, capture_output=True)
+                print("Email sent via git send-email", file=sys.stderr)
+                return True
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                pass
+
+        # Try sendmail
+        try:
+            subprocess.run(
+                ["sendmail", "-t"],
+                input=email_text,
+                text=True,
+                capture_output=True,
+                check=True,
+            )
+            print("Email sent via sendmail", file=sys.stderr)
+            return True
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+
+        # Try msmtp
+        try:
+            subprocess.run(
+                ["msmtp", "-t"],
+                input=email_text,
+                text=True,
+                capture_output=True,
+                check=True,
+            )
+            print("Email sent via msmtp", file=sys.stderr)
+            return True
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+
+        error("Could not send email. Configure git send-email, sendmail, or msmtp.")
+
+    finally:
+        os.unlink(temp_file)
+
+
+def list_providers() -> None:
+    """Print available providers and exit."""
+    print("Available AI Providers:\n")
+    print(f"{'Provider':<12} {'Default Model':<30} {'API Key Variable'}")
+    print(f"{'--------':<12} {'-------------':<30} {'----------------'}")
+    for name, config in PROVIDERS.items():
+        print(f"{name:<12} {config['default_model']:<30} {config['env_var']}")
+    sys.exit(0)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Analyze DPDK patches using AI providers",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    %(prog)s patch.patch                    # Review with default settings
+    %(prog)s -p openai my-patch.patch       # Use OpenAI ChatGPT
+    %(prog)s -f markdown patch.patch        # Output as Markdown
+    %(prog)s -f json -o review.json patch.patch  # Save JSON to file
+    %(prog)s -f html -o review.html patch.patch  # Save HTML to file
+    %(prog)s -r 24.11 patch.patch           # Review for specific release
+    %(prog)s -r 24.11-lts patch.patch       # Review for LTS branch
+    %(prog)s --send-email --to [email protected] series.mbox
+    %(prog)s --send-email --to [email protected] --dry-run series.mbox
+
+Large File Handling:
+    %(prog)s --split-patches series.mbox    # Review each patch separately
+    %(prog)s --split-patches --patch-range 1-5 series.mbox  # Review patches 1-5
+    %(prog)s --large-file=truncate patch.mbox   # Truncate to fit limit
+    %(prog)s --large-file=commits-only series.mbox  # Review commit messages only
+    %(prog)s --large-file=summary series.mbox   # High-level summary only
+    %(prog)s --large-file=chunk series.mbox     # Split and review in chunks
+
+Large File Modes:
+    error       - Fail with error (default)
+    truncate    - Truncate content to fit token limit
+    chunk       - Split into chunks and review each
+    commits-only - Extract and review only commit messages
+    summary     - Request high-level summary review
+
+LTS Releases:
+    Use -r/--release with LTS version (e.g., 24.11-lts, 23.11) to enable
+    stricter review rules: bug fixes only, no new features or APIs.
+    Any DPDK release with minor version .11 is an LTS release.
+
+Token Usage:
+    Token counts are always printed to stderr after each run.
+
+Exit Codes:
+    0 - Clean review (no errors or warnings)
+    1 - Operational failure (missing API key, file not found, etc.)
+    2 - Review found warnings (no errors)
+    3 - Review found errors
+        """,
+    )
+
+    parser.add_argument("patch_file", nargs="?", help="Patch file to analyze")
+    parser.add_argument(
+        "-p",
+        "--provider",
+        choices=PROVIDERS.keys(),
+        default="anthropic",
+        help="AI provider (default: anthropic)",
+    )
+    parser.add_argument(
+        "-a",
+        "--agents",
+        default="AGENTS.md",
+        help="Path to AGENTS.md file (default: AGENTS.md)",
+    )
+    parser.add_argument(
+        "-m",
+        "--model",
+        help="Model to use (default: provider-specific)",
+    )
+    parser.add_argument(
+        "-t",
+        "--tokens",
+        type=int,
+        default=4096,
+        help="Max tokens for response (default: 4096)",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Show API request details",
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        choices=OUTPUT_FORMATS,
+        default="text",
+        dest="output_format",
+        help="Output format: text, markdown, html, json (default: text)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        metavar="FILE",
+        help="Write output to file instead of stdout",
+    )
+    parser.add_argument(
+        "-l",
+        "--list-providers",
+        action="store_true",
+        help="List available providers and exit",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=300,
+        metavar="SECONDS",
+        help="API request timeout in seconds (default: 300)",
+    )
+
+    # Date and release options
+    parser.add_argument(
+        "-D",
+        "--date",
+        metavar="YYYY-MM-DD",
+        help="Review date context (default: today)",
+    )
+    parser.add_argument(
+        "-r",
+        "--release",
+        metavar="VERSION",
+        help="Target DPDK release (e.g., 24.11, 23.11-lts)",
+    )
+
+    # Large file handling options
+    large_group = parser.add_argument_group("Large File Handling")
+    large_group.add_argument(
+        "--large-file",
+        choices=LARGE_FILE_MODES,
+        default="error",
+        metavar="MODE",
+        help="How to handle large files: error (default), truncate, "
+        "chunk, commits-only, summary",
+    )
+    large_group.add_argument(
+        "--max-tokens",
+        type=int,
+        metavar="N",
+        help="Max input tokens (default: provider-specific)",
+    )
+    large_group.add_argument(
+        "--split-patches",
+        action="store_true",
+        help="Split mbox into individual patches and review each separately",
+    )
+    large_group.add_argument(
+        "--patch-range",
+        metavar="N-M",
+        help="Review only patches N through M (1-indexed, use with --split-patches)",
+    )
+
+    # Email options
+    email_group = parser.add_argument_group("Email Options")
+    email_group.add_argument(
+        "--send-email",
+        action="store_true",
+        help="Send review via email",
+    )
+    email_group.add_argument(
+        "--to",
+        action="append",
+        dest="to_addrs",
+        default=[],
+        metavar="ADDRESS",
+        help="Email recipient (can be specified multiple times)",
+    )
+    email_group.add_argument(
+        "--cc",
+        action="append",
+        dest="cc_addrs",
+        default=[],
+        metavar="ADDRESS",
+        help="CC recipient (can be specified multiple times)",
+    )
+    email_group.add_argument(
+        "--from",
+        dest="from_addr",
+        metavar="ADDRESS",
+        help="From address (default: from git config)",
+    )
+    email_group.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show email without sending",
+    )
+
+    args = parser.parse_args()
+
+    if args.list_providers:
+        list_providers()
+
+    # Check patch file is provided
+    if not args.patch_file:
+        parser.error("patch_file is required")
+
+    # Get provider config
+    config = PROVIDERS[args.provider]
+    model = args.model or config["default_model"]
+
+    # Get API key
+    api_key = os.environ.get(config["env_var"])
+    if not api_key:
+        error(f"{config['env_var']} environment variable not set")
+
+    # Validate files
+    agents_path = Path(args.agents)
+    if not agents_path.exists():
+        error(f"AGENTS.md not found: {args.agents}")
+
+    patch_path = Path(args.patch_file)
+    if not patch_path.exists():
+        error(f"Patch file not found: {args.patch_file}")
+
+    # Validate email options
+    if args.send_email and not args.to_addrs:
+        error("--send-email requires at least one --to address")
+
+    # Get from address for email
+    from_addr = args.from_addr
+    if args.send_email and not from_addr:
+        git_name = get_git_config("user.name")
+        git_email = get_git_config("user.email")
+        if git_email:
+            from_addr = f"{git_name} <{git_email}>" if git_name else git_email
+        else:
+            error("No --from specified and git user.email not configured")
+
+    # Determine review date
+    review_date = args.date or date.today().isoformat()
+
+    # Build system prompt with date and release context
+    system_prompt = build_system_prompt(review_date, args.release)
+
+    # Read files
+    agents_content = agents_path.read_text()
+    patch_content = patch_path.read_text()
+    patch_name = patch_path.name
+
+    # Determine max tokens for this provider
+    max_input_tokens = args.max_tokens or PROVIDER_INPUT_LIMITS.get(
+        args.provider, 100000
+    )
+
+    # Estimate token count
+    estimated_tokens = estimate_tokens(patch_content + agents_content)
+
+    # Accumulate token usage across all API calls
+    total_usage = TokenUsage()
+
+    # Parse patch range if specified
+    patch_start, patch_end = None, None
+    if args.patch_range:
+        try:
+            if "-" in args.patch_range:
+                start, end = args.patch_range.split("-", 1)
+                patch_start = int(start)
+                patch_end = int(end)
+            else:
+                patch_start = patch_end = int(args.patch_range)
+        except ValueError:
+            error(f"Invalid --patch-range format: {args.patch_range}")
+        if not args.split_patches:
+            print(
+                "Warning: --patch-range has no effect without --split-patches",
+                file=sys.stderr,
+            )
+
+    # Handle --split-patches mode
+    review_text = ""
+    if args.split_patches:
+        patches = split_mbox_patches(patch_content)
+        total_patches = len(patches)
+
+        if total_patches == 1:
+            print(
+                "Note: Only 1 patch found in mbox, --split-patches has no effect",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                f"Found {total_patches} patches in mbox",
+                file=sys.stderr,
+            )
+
+            # Apply patch range filter
+            if patch_start is not None:
+                if patch_start < 1 or patch_start > total_patches:
+                    error(
+                        f"Patch range start {patch_start} out of range (1-{total_patches})"
+                    )
+                if patch_end < patch_start or patch_end > total_patches:
+                    error(
+                        f"Patch range end {patch_end} out of range ({patch_start}-{total_patches})"
+                    )
+                patches = patches[patch_start - 1 : patch_end]
+                print(
+                    f"Reviewing patches {patch_start}-{patch_end} ({len(patches)} patches)",
+                    file=sys.stderr,
+                )
+
+            # Review each patch separately
+            all_reviews = []
+            for i, patch in enumerate(patches, patch_start or 1):
+                patch_label = f"Patch {i}/{total_patches}"
+                print(f"\nReviewing {patch_label}...", file=sys.stderr)
+
+                review_text, call_usage = call_api(
+                    args.provider,
+                    api_key,
+                    model,
+                    args.tokens,
+                    system_prompt,
+                    agents_content,
+                    patch,
+                    f"{patch_name} ({patch_label})",
+                    args.output_format,
+                    args.verbose,
+                    args.timeout,
+                )
+                total_usage.add(call_usage)
+                all_reviews.append((patch_label, review_text))
+
+            # Combine reviews
+            review_text = format_combined_reviews(
+                all_reviews, args.output_format, patch_name
+            )
+
+            # Skip the normal API call
+            estimated_tokens = 0  # Bypass size check since we've already processed
+
+    # Check if content is too large
+    is_large = estimated_tokens > max_input_tokens
+
+    if is_large:
+        print(
+            f"Warning: Estimated {estimated_tokens:,} tokens exceeds limit of "
+            f"{max_input_tokens:,}",
+            file=sys.stderr,
+        )
+
+        if args.large_file == "error":
+            error(
+                f"Patch file too large ({estimated_tokens:,} tokens). "
+                f"Use --large-file=truncate|chunk|commits-only|summary to handle, "
+                f"or --split-patches to review patches individually."
+            )
+        elif args.large_file == "truncate":
+            print("Truncating content to fit token limit...", file=sys.stderr)
+            patch_content, was_truncated = truncate_content(
+                patch_content, max_input_tokens
+            )
+            if was_truncated:
+                print("Content was truncated.", file=sys.stderr)
+        elif args.large_file == "commits-only":
+            print("Extracting commit messages only...", file=sys.stderr)
+            patch_content = extract_commit_messages(patch_content)
+            new_estimate = estimate_tokens(patch_content + agents_content)
+            print(
+                f"Reduced to ~{new_estimate:,} tokens (commit messages only)",
+                file=sys.stderr,
+            )
+            if new_estimate > max_input_tokens:
+                patch_content, _ = truncate_content(patch_content, max_input_tokens)
+        elif args.large_file == "summary":
+            print("Using summary mode for large patch...", file=sys.stderr)
+            system_prompt += get_summary_prompt()
+            patch_content, _ = truncate_content(patch_content, max_input_tokens)
+        elif args.large_file == "chunk":
+            print("Processing in chunks...", file=sys.stderr)
+            all_reviews = []
+            for chunk, chunk_num, total_chunks in chunk_content(
+                patch_content, max_input_tokens
+            ):
+                chunk_label = f"Chunk {chunk_num}/{total_chunks}"
+                print(f"Reviewing {chunk_label}...", file=sys.stderr)
+
+                review_text, call_usage = call_api(
+                    args.provider,
+                    api_key,
+                    model,
+                    args.tokens,
+                    system_prompt,
+                    agents_content,
+                    chunk,
+                    f"{patch_name} ({chunk_label})",
+                    args.output_format,
+                    args.verbose,
+                    args.timeout,
+                )
+                total_usage.add(call_usage)
+                all_reviews.append((chunk_label, review_text))
+
+            # Combine chunk reviews
+            review_text = format_combined_reviews(
+                all_reviews, args.output_format, patch_name
+            )
+
+            # Skip the normal single API call below
+            estimated_tokens = 0
+
+    if args.verbose:
+        print("=== Request ===", file=sys.stderr)
+        print(f"Provider: {args.provider}", file=sys.stderr)
+        print(f"Model: {model}", file=sys.stderr)
+        print(f"Review date: {review_date}", file=sys.stderr)
+        if args.release:
+            lts_status = " (LTS)" if is_lts_release(args.release) else ""
+            print(f"Target release: {args.release}{lts_status}", file=sys.stderr)
+        print(f"Output format: {args.output_format}", file=sys.stderr)
+        print(f"AGENTS file: {args.agents}", file=sys.stderr)
+        print(f"Patch file: {args.patch_file}", file=sys.stderr)
+        print(f"Estimated tokens: {estimated_tokens:,}", file=sys.stderr)
+        print(f"Max input tokens: {max_input_tokens:,}", file=sys.stderr)
+        if args.large_file != "error":
+            print(f"Large file mode: {args.large_file}", file=sys.stderr)
+        if args.split_patches:
+            print("Split patches: yes", file=sys.stderr)
+        if args.output:
+            print(f"Output file: {args.output}", file=sys.stderr)
+        if args.send_email:
+            print("Send email: yes", file=sys.stderr)
+            print(f"To: {', '.join(args.to_addrs)}", file=sys.stderr)
+            if args.cc_addrs:
+                print(f"Cc: {', '.join(args.cc_addrs)}", file=sys.stderr)
+            print(f"From: {from_addr}", file=sys.stderr)
+        print("===============", file=sys.stderr)
+
+    # Call API (unless already processed via chunks/split)
+    if estimated_tokens > 0:  # Not already processed
+        review_text, call_usage = call_api(
+            args.provider,
+            api_key,
+            model,
+            args.tokens,
+            system_prompt,
+            agents_content,
+            patch_content,
+            patch_name,
+            args.output_format,
+            args.verbose,
+            args.timeout,
+        )
+        total_usage.add(call_usage)
+
+    if not review_text:
+        error(f"No response received from {args.provider}")
+
+    # Format output based on requested format
+    provider_name = config["name"]
+
+    if args.output_format == "json":
+        # For JSON, try to parse and add metadata
+        try:
+            review_data = json.loads(review_text)
+        except json.JSONDecodeError:
+            # If AI didn't return valid JSON, wrap the text
+            review_data = {"raw_review": review_text}
+
+        usage_data = {
+            "api_calls": total_usage.api_calls,
+            "input_tokens": total_usage.input_tokens,
+            "output_tokens": total_usage.output_tokens,
+            "total_tokens": total_usage.input_tokens + total_usage.output_tokens,
+        }
+        if total_usage.cache_creation_tokens:
+            usage_data["cache_creation_tokens"] = total_usage.cache_creation_tokens
+        if total_usage.cache_read_tokens:
+            usage_data["cache_read_tokens"] = total_usage.cache_read_tokens
+
+        output_data = {
+            "metadata": {
+                "patch_file": patch_name,
+                "provider": args.provider,
+                "provider_name": provider_name,
+                "model": model,
+                "review_date": review_date,
+                "target_release": args.release,
+                "is_lts": is_lts_release(args.release) if args.release else False,
+                "token_usage": usage_data,
+            },
+            "review": review_data,
+        }
+        output_text = json.dumps(output_data, indent=2)
+    elif args.output_format == "html":
+        # Wrap HTML content with header
+        release_info = ""
+        if args.release:
+            lts_badge = " (LTS)" if is_lts_release(args.release) else ""
+            release_info = f"<br>Target release: {args.release}{lts_badge}"
+        output_text = f"""<!-- AI-generated review of {patch_name} -->
+<!-- Reviewed using {provider_name} ({model}) on {review_date} -->
+<div class="patch-review">
+<h1>Patch Review: {patch_name}</h1>
+<p class="review-meta">Reviewed by {provider_name} ({model}) on {review_date}{release_info}</p>
+{review_text}
+</div>
+"""
+    elif args.output_format == "markdown":
+        release_info = ""
+        if args.release:
+            lts_badge = " (LTS)" if is_lts_release(args.release) else ""
+            release_info = f"\n*Target release: {args.release}{lts_badge}*\n"
+        output_text = f"""# Patch Review: {patch_name}
+
+*Reviewed by {provider_name} ({model}) on {review_date}*
+{release_info}
+{review_text}
+"""
+    else:  # text
+        release_info = ""
+        if args.release:
+            lts_badge = " (LTS)" if is_lts_release(args.release) else ""
+            release_info = f"Target release: {args.release}{lts_badge}\n"
+        output_text = f"=== Patch Review: {patch_name} (via {provider_name}) ===\n"
+        output_text += f"Review date: {review_date}\n"
+        output_text += release_info
+        output_text += "\n" + review_text
+
+    # Write output
+    if args.output:
+        Path(args.output).write_text(output_text)
+        print(f"Review written to: {args.output}", file=sys.stderr)
+    else:
+        print(output_text)
+
+    # Print token usage summary
+    if total_usage.api_calls > 0:
+        print("", file=sys.stderr)
+        print(
+            format_token_summary(total_usage, args.provider, model),
+            file=sys.stderr,
+        )
+
+    # Send email if requested
+    if args.send_email:
+        # Email always uses plain text - warn if different format requested
+        if args.output_format != "text":
+            print(
+                f"Note: Email will be sent as plain text regardless of "
+                f"--format={args.output_format}",
+                file=sys.stderr,
+            )
+
+        in_reply_to = get_last_message_id(patch_content)
+        orig_subject = get_last_subject(patch_content)
+
+        if orig_subject:
+            # Remove [PATCH n/m] prefix
+            review_subject = re.sub(r"^\[PATCH[^\]]*\]\s*", "", orig_subject)
+            review_subject = f"[REVIEW] {review_subject}"
+        else:
+            review_subject = f"[REVIEW] {patch_name}"
+
+        # Build email body - always use plain text version
+        release_info = ""
+        if args.release:
+            lts_badge = " (LTS)" if is_lts_release(args.release) else ""
+            release_info = f"Target release: {args.release}{lts_badge}\n"
+
+        email_body = f"""AI-generated review of {patch_name}
+Reviewed using {provider_name} ({model}) on {review_date}
+{release_info}
+This is an automated review. Please verify all suggestions.
+
+---
+
+{review_text}
+"""
+
+        if args.verbose:
+            print("", file=sys.stderr)
+            print("=== Email Details ===", file=sys.stderr)
+            print(f"Subject: {review_subject}", file=sys.stderr)
+            print(f"In-Reply-To: {in_reply_to}", file=sys.stderr)
+            print("=====================", file=sys.stderr)
+
+        send_email(
+            args.to_addrs,
+            args.cc_addrs,
+            from_addr,
+            review_subject,
+            in_reply_to,
+            email_body,
+            args.dry_run,
+        )
+
+        if not args.dry_run:
+            print("", file=sys.stderr)
+            print(f"Review sent to: {', '.join(args.to_addrs)}", file=sys.stderr)
+
+    # Exit with code based on review severity
+    sys.exit(classify_review(review_text, args.output_format))
+
+
+if __name__ == "__main__":
+    main()

new file mode 100755
index 0000000000..b4813cb6a7
@@ -0,0 +1,263 @@
+#!/bin/bash
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2026 Stephen Hemminger
+
+# Compare DPDK patch reviews across multiple AI providers
+# Runs analyze-patch.py with each available provider
+
+set -o pipefail
+
+SCRIPT_DIR="$(dirname "$(readlink -f "$0")")"
+ANALYZE_SCRIPT="${SCRIPT_DIR}/analyze-patch.py"
+AGENTS_FILE="AGENTS.md"
+OUTPUT_DIR=""
+PROVIDERS=""
+FORMAT="text"
+VERBOSE=""
+EXTRA_ARGS=()
+
+usage() {
+    cat <<EOF
+Usage: $(basename "$0") [OPTIONS] <patch-file>
+
+Compare DPDK patch reviews across multiple AI providers.
+
+Options:
+    -a, --agents FILE      Path to AGENTS.md file (default: AGENTS.md)
+    -o, --output DIR       Save individual reviews to directory
+    -p, --providers LIST   Comma-separated list of providers to use
+                           (default: all providers with API keys set)
+    -f, --format FORMAT    Output format: text, markdown, html, json
+                           (default: text)
+    -t, --tokens N         Max tokens for response
+    -D, --date DATE        Review date context (YYYY-MM-DD)
+    -r, --release VERSION  Target DPDK release (e.g., 24.11, 23.11-lts)
+    --split-patches        Split mbox into individual patches
+    --patch-range N-M      Review only patches N through M
+    --large-file MODE      Handle large files: error, truncate, chunk,
+                           commits-only, summary
+    --max-tokens N         Max input tokens
+    -v, --verbose          Show verbose output from each provider
+    -h, --help             Show this help message
+
+Environment Variables:
+    Set API keys for providers you want to use:
+    ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, GOOGLE_API_KEY
+
+Examples:
+    $(basename "$0") my-patch.patch
+    $(basename "$0") -p anthropic,openai my-patch.patch
+    $(basename "$0") -o ./reviews -f markdown my-patch.patch
+    $(basename "$0") -r 24.11 --split-patches series.mbox
+EOF
+    exit "${1:-0}"
+}
+
+error() {
+    echo "Error: $1" >&2
+    exit 1
+}
+
+# Check which providers have API keys configured
+get_available_providers() {
+    local available=""
+
+    [[ -n "$ANTHROPIC_API_KEY" ]] && available="${available}anthropic,"
+    [[ -n "$OPENAI_API_KEY" ]] && available="${available}openai,"
+    [[ -n "$XAI_API_KEY" ]] && available="${available}xai,"
+    [[ -n "$GOOGLE_API_KEY" ]] && available="${available}google,"
+
+    # Remove trailing comma
+    echo "${available%,}"
+}
+
+# Get file extension for format
+get_extension() {
+    case "$1" in
+        text)     echo "txt" ;;
+        markdown) echo "md" ;;
+        html)     echo "html" ;;
+        json)     echo "json" ;;
+        *)        echo "txt" ;;
+    esac
+}
+
+# Parse command line options
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -a|--agents)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            AGENTS_FILE="$2"
+            shift 2
+            ;;
+        -o|--output)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            OUTPUT_DIR="$2"
+            shift 2
+            ;;
+        -p|--providers)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            PROVIDERS="$2"
+            shift 2
+            ;;
+        -f|--format)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            FORMAT="$2"
+            shift 2
+            ;;
+        -t|--tokens)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            EXTRA_ARGS+=("-t" "$2")
+            shift 2
+            ;;
+        -D|--date)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            EXTRA_ARGS+=("-D" "$2")
+            shift 2
+            ;;
+        -r|--release)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            EXTRA_ARGS+=("-r" "$2")
+            shift 2
+            ;;
+        --split-patches)
+            EXTRA_ARGS+=("--split-patches")
+            shift
+            ;;
+        --patch-range)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            EXTRA_ARGS+=("--patch-range" "$2")
+            shift 2
+            ;;
+        --large-file)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            EXTRA_ARGS+=("--large-file" "$2")
+            shift 2
+            ;;
+        --large-file=*)
+            EXTRA_ARGS+=("$1")
+            shift
+            ;;
+        --max-tokens)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            EXTRA_ARGS+=("--max-tokens" "$2")
+            shift 2
+            ;;
+        -v|--verbose)
+            VERBOSE="-v"
+            shift
+            ;;
+        -h|--help)
+            usage 0
+            ;;
+        -*)
+            error "Unknown option: $1"
+            ;;
+        *)
+            break
+            ;;
+    esac
+done
+
+# Check for required arguments
+if [[ $# -lt 1 ]]; then
+    echo "Error: No patch file specified" >&2
+    usage 1
+fi
+
+PATCH_FILE="$1"
+
+if [[ ! -f "$PATCH_FILE" ]]; then
+    error "Patch file not found: $PATCH_FILE"
+fi
+
+if [[ ! -f "$ANALYZE_SCRIPT" ]]; then
+    error "analyze-patch.py not found: $ANALYZE_SCRIPT"
+fi
+
+if [[ ! -f "$AGENTS_FILE" ]]; then
+    error "AGENTS.md not found: $AGENTS_FILE"
+fi
+
+# Validate format
+case "$FORMAT" in
+    text|markdown|html|json) ;;
+    *) error "Invalid format: $FORMAT (must be text, markdown, html, or json)" ;;
+esac
+
+# Get providers to use
+if [[ -z "$PROVIDERS" ]]; then
+    PROVIDERS=$(get_available_providers)
+fi
+
+if [[ -z "$PROVIDERS" ]]; then
+    error "No API keys configured. Set at least one of: "\
+"ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, GOOGLE_API_KEY"
+fi
+
+# Create output directory if specified
+if [[ -n "$OUTPUT_DIR" ]]; then
+    mkdir -p "$OUTPUT_DIR"
+fi
+
+PATCH_BASENAME=$(basename "$PATCH_FILE")
+PATCH_STEM="${PATCH_BASENAME%.*}"
+EXT=$(get_extension "$FORMAT")
+
+echo "Reviewing patch: $PATCH_BASENAME"
+echo "Providers: $PROVIDERS"
+echo "Format: $FORMAT"
+echo "========================================"
+echo ""
+
+# Run review for each provider, continue on failure
+IFS=',' read -ra PROVIDER_LIST <<< "$PROVIDERS"
+failures=0
+for provider in "${PROVIDER_LIST[@]}"; do
+    echo ">>> Running review with: $provider"
+    echo ""
+
+    if [[ -n "$OUTPUT_DIR" ]]; then
+        OUTPUT_FILE="${OUTPUT_DIR}/${PATCH_STEM}-${provider}.${EXT}"
+        if python3 "$ANALYZE_SCRIPT" \
+            -p "$provider" \
+            -a "$AGENTS_FILE" \
+            -f "$FORMAT" \
+            ${VERBOSE:+"$VERBOSE"} \
+            "${EXTRA_ARGS[@]}" \
+            "$PATCH_FILE" | tee "$OUTPUT_FILE"; then
+            echo ""
+            echo "Saved to: $OUTPUT_FILE"
+        else
+            echo "FAILED: $provider review failed" >&2
+            rm -f "$OUTPUT_FILE"
+            ((failures++)) || true
+        fi
+    else
+        if ! python3 "$ANALYZE_SCRIPT" \
+            -p "$provider" \
+            -a "$AGENTS_FILE" \
+            -f "$FORMAT" \
+            ${VERBOSE:+"$VERBOSE"} \
+            "${EXTRA_ARGS[@]}" \
+            "$PATCH_FILE"; then
+            echo "FAILED: $provider review failed" >&2
+            ((failures++)) || true
+        fi
+    fi
+
+    echo ""
+    echo "========================================"
+    echo ""
+done
+
+echo "Review comparison complete."
+
+if [[ -n "$OUTPUT_DIR" ]]; then
+    echo "All reviews saved to: $OUTPUT_DIR"
+fi
+
+if [[ $failures -gt 0 ]]; then
+    echo "$failures provider(s) failed." >&2
+    exit 1
+fi

new file mode 100755
index 0000000000..d9582f8978
@@ -0,0 +1,1184 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2026 Stephen Hemminger
+
+"""
+Review DPDK documentation files using AI providers.
+
+Produces a diff file and commit message compliant with DPDK standards.
+Accepts multiple documentation files and generates output for each.
+Supported providers: Anthropic Claude, OpenAI ChatGPT, xAI Grok, Google Gemini
+"""
+
+import argparse
+import getpass
+import json
+import os
+import re
+import smtplib
+import ssl
+import subprocess
+import sys
+from dataclasses import dataclass
+from email.message import EmailMessage
+from pathlib import Path
+from typing import Any, NoReturn
+from urllib.request import Request, urlopen
+from urllib.error import URLError, HTTPError
+
+# Map output format to file extension
+FORMAT_EXTENSIONS = {
+    "text": ".txt",
+    "markdown": ".md",
+    "html": ".html",
+    "json": ".json",
+}
+
+# Additional markers for extracting diff/msg (used with --diff flag)
+DIFF_MARKERS_INSTRUCTION = """
+
+ADDITIONALLY, at the end of your response, include these exact markers for automated extraction:
+---COMMIT_MESSAGE_START---
+(same commit message as above)
+---COMMIT_MESSAGE_END---
+
+---UNIFIED_DIFF_START---
+(same unified diff as above)
+---UNIFIED_DIFF_END---
+"""
+
+# Provider configurations
+PROVIDERS = {
+    "anthropic": {
+        "name": "Claude",
+        "endpoint": "https://api.anthropic.com/v1/messages",
+        "default_model": "claude-sonnet-4-5-20250929",
+        "env_var": "ANTHROPIC_API_KEY",
+    },
+    "openai": {
+        "name": "ChatGPT",
+        "endpoint": "https://api.openai.com/v1/chat/completions",
+        "default_model": "gpt-4.1",
+        "env_var": "OPENAI_API_KEY",
+    },
+    "xai": {
+        "name": "Grok",
+        "endpoint": "https://api.x.ai/v1/chat/completions",
+        "default_model": "grok-4-1-fast-non-reasoning",
+        "env_var": "XAI_API_KEY",
+    },
+    "google": {
+        "name": "Gemini",
+        "endpoint": "https://generativelanguage.googleapis.com/v1beta/models",
+        "default_model": "gemini-3-flash-preview",
+        "env_var": "GOOGLE_API_KEY",
+    },
+}
+
+
+@dataclass
+class TokenUsage:
+    """Accumulated token usage across API calls."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_creation_tokens: int = 0
+    cache_read_tokens: int = 0
+    api_calls: int = 0
+
+    def add(self, other: "TokenUsage") -> None:
+        """Accumulate usage from another TokenUsage."""
+        self.input_tokens += other.input_tokens
+        self.output_tokens += other.output_tokens
+        self.cache_creation_tokens += other.cache_creation_tokens
+        self.cache_read_tokens += other.cache_read_tokens
+        self.api_calls += other.api_calls
+
+
+# Pricing per million tokens (USD) - update as prices change.
+# Keys are (provider, model-prefix) tuples; first prefix match wins.
+# "default" key is fallback for unknown models within a provider.
+def format_token_summary(usage: TokenUsage, provider: str, model: str) -> str:
+    """Format a token usage summary string."""
+    lines = ["=== Token Usage Summary ==="]
+    lines.append(f"API calls:     {usage.api_calls}")
+    lines.append(f"Input tokens:  {usage.input_tokens:,}")
+    lines.append(f"Output tokens: {usage.output_tokens:,}")
+    if usage.cache_creation_tokens:
+        lines.append(f"Cache write:   {usage.cache_creation_tokens:,}")
+    if usage.cache_read_tokens:
+        lines.append(f"Cache read:    {usage.cache_read_tokens:,}")
+    total = usage.input_tokens + usage.output_tokens
+    lines.append(f"Total tokens:  {total:,}")
+    lines.append("=" * 27)
+    return "\n".join(lines)
+
+
+# Commit prefix mappings based on file path
+COMMIT_PREFIX_MAP = [
+    ("doc/guides/prog_guide/", "doc/guides/prog_guide:"),
+    ("doc/guides/sample_app_ug/", "doc/guides/sample_app:"),
+    ("doc/guides/nics/", "doc/guides/nics:"),
+    ("doc/guides/cryptodevs/", "doc/guides/cryptodevs:"),
+    ("doc/guides/compressdevs/", "doc/guides/compressdevs:"),
+    ("doc/guides/eventdevs/", "doc/guides/eventdevs:"),
+    ("doc/guides/rawdevs/", "doc/guides/rawdevs:"),
+    ("doc/guides/bbdevs/", "doc/guides/bbdevs:"),
+    ("doc/guides/gpus/", "doc/guides/gpus:"),
+    ("doc/guides/dmadevs/", "doc/guides/dmadevs:"),
+    ("doc/guides/regexdevs/", "doc/guides/regexdevs:"),
+    ("doc/guides/mldevs/", "doc/guides/mldevs:"),
+    ("doc/guides/rel_notes/", "doc/guides/rel_notes:"),
+    ("doc/guides/linux_gsg/", "doc/guides/linux_gsg:"),
+    ("doc/guides/freebsd_gsg/", "doc/guides/freebsd_gsg:"),
+    ("doc/guides/windows_gsg/", "doc/guides/windows_gsg:"),
+    ("doc/guides/tools/", "doc/guides/tools:"),
+    ("doc/guides/testpmd_app_ug/", "doc/guides/testpmd:"),
+    ("doc/guides/howto/", "doc/guides/howto:"),
+    ("doc/guides/contributing/", "doc/guides/contributing:"),
+    ("doc/guides/platform/", "doc/guides/platform:"),
+    ("doc/guides/", "doc:"),
+    ("doc/api/", "doc/api:"),
+    ("doc/", "doc:"),
+]
+
+SYSTEM_PROMPT = """\
+You are an expert technical documentation reviewer for DPDK.
+Your task is to review documentation files and suggest improvements for:
+- Spelling errors
+- Grammar issues
+- Technical correctness
+- Clarity and readability
+- Consistency with DPDK terminology
+
+IMPORTANT COMMIT MESSAGE RULES (from check-git-log.sh):
+- Subject line MUST be ≤60 characters
+- Format: "prefix: lowercase description"
+- First word after colon must be lowercase (except acronyms like Rx, Tx, VF, MAC, API)
+- Use imperative mood (e.g., "fix typo" not "fixed typo" or "fixes typo")
+- NO trailing period on subject line
+- NO punctuation marks: , ; ! ? & |
+- NO underscores in subject after colon
+- Body lines wrapped at 75 characters
+- Body must NOT start with "It"
+- Do NOT include Signed-off-by (user adds via git commit --sign)
+- Only use "Fixes:" tag for actual errors in documentation, not style improvements
+
+Case-sensitive terms (must use exact case):
+- Rx, Tx (not RX, TX, rx, tx)
+- VF, PF (not vf, pf)
+- MAC, VLAN, RSS, API
+- Linux, Windows, FreeBSD
+
+For style/clarity improvements, do NOT use Fixes tag.
+For actual errors (wrong information, broken examples), include Fixes tag \
+if you can identify the commit."""
+
+FORMAT_INSTRUCTIONS = {
+    "text": """
+OUTPUT FORMAT:
+You must output exactly two sections:
+
+1. COMMIT_MESSAGE section containing the complete commit message
+2. UNIFIED_DIFF section containing the unified diff
+
+Use these exact markers:
+---COMMIT_MESSAGE_START---
+(commit message here)
+---COMMIT_MESSAGE_END---
+
+---UNIFIED_DIFF_START---
+(unified diff here)
+---UNIFIED_DIFF_END---
+
+The diff should be in unified format that can be applied with "git apply".
+If no changes are needed, output empty sections with a note.""",
+    "markdown": """
+OUTPUT FORMAT:
+Provide your review in Markdown format with:
+
+## Summary
+Brief description of changes
+
+## Commit Message
+```
+(complete commit message here, ready to use)
+```
+
+## Changes
+For each change:
+### Issue N: Brief title
+- **Location**: file path and line
+- **Problem**: description
+- **Fix**: suggested correction
+
+## Unified Diff
+```diff
+(unified diff here)
+```""",
+    "html": """
+OUTPUT FORMAT:
+Provide your review in HTML format with:
+- <h2> for sections (Summary, Commit Message, Changes, Diff)
+- <pre><code> for commit message and diff
+- <ul>/<li> for individual issues
+- Do NOT include <html>, <head>, or <body> tags - just the content
+
+Include sections for: Summary, Commit Message, Changes, Unified Diff""",
+    "json": """
+OUTPUT FORMAT:
+Provide your review as JSON with this structure:
+{
+  "summary": "Brief description of changes",
+  "commit_message": "Complete commit message ready to use",
+  "changes": [
+    {
+      "type": "spelling|grammar|technical|clarity|style",
+      "location": "line number or section",
+      "original": "original text",
+      "suggested": "corrected text",
+      "reason": "why this change"
+    }
+  ],
+  "diff": "unified diff as a string",
+  "stats": {
+    "total_issues": 0,
+    "spelling": 0,
+    "grammar": 0,
+    "technical": 0,
+    "clarity": 0
+  }
+}
+Output ONLY valid JSON, no markdown code fences or other text.""",
+}
+
+USER_PROMPT = """\
+Review the following DPDK documentation file and provide improvements.
+
+File path: {doc_file}
+Commit message prefix to use: {commit_prefix}
+
+{format_instruction}
+
+---DOCUMENT CONTENT---
+"""
+
+
+def error(msg: str) -> NoReturn:
+    """Print error message and exit."""
+    print(f"Error: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def get_git_config(key: str) -> str | None:
+    """Get a value from git config."""
+    try:
+        result = subprocess.run(
+            ["git", "config", "--get", key],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+
+def get_smtp_config() -> dict[str, Any]:
+    """Get SMTP configuration from git config sendemail settings."""
+    config = {
+        "server": get_git_config("sendemail.smtpserver"),
+        "port": get_git_config("sendemail.smtpserverport"),
+        "user": get_git_config("sendemail.smtpuser"),
+        "encryption": get_git_config("sendemail.smtpencryption"),
+        "password": get_git_config("sendemail.smtppass"),
+    }
+
+    # Set defaults
+    if not config["port"]:
+        if config["encryption"] == "ssl":
+            config["port"] = "465"
+        else:
+            config["port"] = "587"
+
+    # Convert port to int
+    config["port"] = int(config["port"])
+
+    return config
+
+
+def get_commit_prefix(filepath: str) -> str:
+    """Determine commit message prefix from file path."""
+    for prefix_path, prefix in COMMIT_PREFIX_MAP:
+        if filepath.startswith(prefix_path):
+            return prefix
+    return "doc:"
+
+
+def build_user_prompt(
+    doc_file: str,
+    commit_prefix: str,
+    output_format: str = "text",
+    include_diff_markers: bool = False,
+) -> str:
+    """Build the user prompt with format instructions."""
+    format_instruction = FORMAT_INSTRUCTIONS.get(output_format, "")
+    if include_diff_markers and output_format not in ("text", "json"):
+        format_instruction += DIFF_MARKERS_INSTRUCTION
+    return USER_PROMPT.format(
+        doc_file=doc_file,
+        commit_prefix=commit_prefix,
+        format_instruction=format_instruction,
+    )
+
+
+def build_anthropic_request(
+    model: str,
+    max_tokens: int,
+    agents_content: str,
+    doc_content: str,
+    doc_file: str,
+    commit_prefix: str,
+    output_format: str = "text",
+    include_diff_markers: bool = False,
+) -> dict[str, Any]:
+    """Build request payload for Anthropic API."""
+    user_prompt = build_user_prompt(
+        doc_file, commit_prefix, output_format, include_diff_markers
+    )
+    return {
+        "model": model,
+        "max_tokens": max_tokens,
+        "system": [
+            {"type": "text", "text": SYSTEM_PROMPT},
+            {
+                "type": "text",
+                "text": agents_content,
+                "cache_control": {"type": "ephemeral"},
+            },
+        ],
+        "messages": [
+            {
+                "role": "user",
+                "content": user_prompt + doc_content,
+            }
+        ],
+    }
+
+
+def build_openai_request(
+    model: str,
+    max_tokens: int,
+    agents_content: str,
+    doc_content: str,
+    doc_file: str,
+    commit_prefix: str,
+    output_format: str = "text",
+    include_diff_markers: bool = False,
+) -> dict[str, Any]:
+    """Build request payload for OpenAI-compatible APIs."""
+    user_prompt = build_user_prompt(
+        doc_file, commit_prefix, output_format, include_diff_markers
+    )
+    return {
+        "model": model,
+        "max_tokens": max_tokens,
+        "messages": [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "system", "content": agents_content},
+            {
+                "role": "user",
+                "content": user_prompt + doc_content,
+            },
+        ],
+    }
+
+
+def build_google_request(
+    max_tokens: int,
+    agents_content: str,
+    doc_content: str,
+    doc_file: str,
+    commit_prefix: str,
+    output_format: str = "text",
+    include_diff_markers: bool = False,
+) -> dict[str, Any]:
+    """Build request payload for Google Gemini API."""
+    user_prompt = build_user_prompt(
+        doc_file, commit_prefix, output_format, include_diff_markers
+    )
+    return {
+        "systemInstruction": {
+            "parts": [
+                {"text": SYSTEM_PROMPT},
+                {"text": agents_content},
+            ],
+        },
+        "contents": [
+            {
+                "role": "user",
+                "parts": [{"text": user_prompt + doc_content}],
+            },
+        ],
+        "generationConfig": {"maxOutputTokens": max_tokens},
+    }
+
+
+def call_api(
+    provider: str,
+    api_key: str,
+    model: str,
+    max_tokens: int,
+    agents_content: str,
+    doc_content: str,
+    doc_file: str,
+    commit_prefix: str,
+    output_format: str = "text",
+    include_diff_markers: bool = False,
+    verbose: bool = False,
+    timeout: int = 120,
+) -> tuple[str, TokenUsage]:
+    """Make API request to the specified provider.
+
+    Returns a tuple of (response_text, token_usage).
+    """
+    config = PROVIDERS[provider]
+
+    # Build request based on provider
+    if provider == "anthropic":
+        request_data = build_anthropic_request(
+            model,
+            max_tokens,
+            agents_content,
+            doc_content,
+            doc_file,
+            commit_prefix,
+            output_format,
+            include_diff_markers,
+        )
+        headers = {
+            "Content-Type": "application/json",
+            "x-api-key": api_key,
+            "anthropic-version": "2023-06-01",
+        }
+        url = config["endpoint"]
+    elif provider == "google":
+        request_data = build_google_request(
+            max_tokens,
+            agents_content,
+            doc_content,
+            doc_file,
+            commit_prefix,
+            output_format,
+            include_diff_markers,
+        )
+        headers = {"Content-Type": "application/json"}
+        url = f"{config['endpoint']}/{model}:generateContent?key={api_key}"
+    else:  # openai, xai
+        request_data = build_openai_request(
+            model,
+            max_tokens,
+            agents_content,
+            doc_content,
+            doc_file,
+            commit_prefix,
+            output_format,
+            include_diff_markers,
+        )
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        }
+        url = config["endpoint"]
+
+    # Make request
+    request_body = json.dumps(request_data).encode("utf-8")
+    req = Request(url, data=request_body, headers=headers)
+
+    try:
+        with urlopen(req, timeout=timeout) as response:
+            result = json.loads(response.read().decode("utf-8"))
+    except HTTPError as e:
+        error_body = e.read().decode("utf-8")
+        try:
+            error_data = json.loads(error_body)
+            error(f"API error: {error_data.get('error', error_body)}")
+        except json.JSONDecodeError:
+            error(f"API error ({e.code}): {error_body}")
+    except URLError as e:
+        if isinstance(e.reason, TimeoutError):
+            error(f"Request timed out after {timeout} seconds")
+        error(f"Connection error: {e.reason}")
+
+    # Extract token usage
+    usage = TokenUsage(api_calls=1)
+    if provider == "anthropic":
+        raw_usage = result.get("usage", {})
+        usage.input_tokens = raw_usage.get("input_tokens", 0)
+        usage.output_tokens = raw_usage.get("output_tokens", 0)
+        usage.cache_creation_tokens = raw_usage.get("cache_creation_input_tokens", 0)
+        usage.cache_read_tokens = raw_usage.get("cache_read_input_tokens", 0)
+    elif provider == "google":
+        raw_usage = result.get("usageMetadata", {})
+        usage.input_tokens = raw_usage.get("promptTokenCount", 0)
+        usage.output_tokens = raw_usage.get("candidatesTokenCount", 0)
+    else:  # openai, xai
+        raw_usage = result.get("usage", {})
+        usage.input_tokens = raw_usage.get("prompt_tokens", 0)
+        usage.output_tokens = raw_usage.get("completion_tokens", 0)
+        # OpenAI cache details (if available)
+        cache_details = raw_usage.get("prompt_tokens_details", {})
+        if cache_details:
+            usage.cache_read_tokens = cache_details.get("cached_tokens", 0)
+
+    # Show per-call details in verbose mode
+    if verbose:
+        print("=== Token Usage ===", file=sys.stderr)
+        print(f"Input tokens: {usage.input_tokens:,}", file=sys.stderr)
+        print(f"Output tokens: {usage.output_tokens:,}", file=sys.stderr)
+        if usage.cache_creation_tokens:
+            print(
+                f"Cache creation: {usage.cache_creation_tokens:,}",
+                file=sys.stderr,
+            )
+        if usage.cache_read_tokens:
+            print(
+                f"Cache read: {usage.cache_read_tokens:,}",
+                file=sys.stderr,
+            )
+        print("===================", file=sys.stderr)
+
+    # Extract response text
+    if provider == "anthropic":
+        if "error" in result:
+            error(f"API error: {result['error'].get('message', result)}")
+        content = result.get("content", [])
+        text = "".join(
+            block.get("text", "") for block in content if block.get("type") == "text"
+        )
+        return text, usage
+    elif provider == "google":
+        if "error" in result:
+            error(f"API error: {result['error'].get('message', result)}")
+        candidates = result.get("candidates", [])
+        if not candidates:
+            error("No response from Gemini")
+        parts = candidates[0].get("content", {}).get("parts", [])
+        text = "".join(part.get("text", "") for part in parts)
+        return text, usage
+    else:  # openai, xai
+        if "error" in result:
+            error(f"API error: {result['error'].get('message', result)}")
+        choices = result.get("choices", [])
+        if not choices:
+            error("No response from API")
+        text = choices[0].get("message", {}).get("content", "")
+        return text, usage
+
+
+def parse_review_text(review_text: str) -> tuple[str, str]:
+    """Extract commit message and diff from text format response."""
+    commit_msg = ""
+    diff = ""
+
+    # Extract commit message
+    msg_match = re.search(
+        r"---COMMIT_MESSAGE_START---\s*\n(.*?)\n---COMMIT_MESSAGE_END---",
+        review_text,
+        re.DOTALL,
+    )
+    if msg_match:
+        commit_msg = msg_match.group(1).strip()
+
+    # Extract unified diff
+    diff_match = re.search(
+        r"---UNIFIED_DIFF_START---\s*\n(.*?)\n---UNIFIED_DIFF_END---",
+        review_text,
+        re.DOTALL,
+    )
+    if diff_match:
+        diff = diff_match.group(1).strip()
+        # Clean up any markdown code fence if present
+        diff = re.sub(r"^```diff\s*\n?", "", diff)
+        diff = re.sub(r"\n?```\s*$", "", diff)
+
+    return commit_msg, diff
+
+
+def strip_diff_markers(text: str) -> str:
+    """Remove the diff/msg extraction markers from text."""
+    # Remove commit message markers and content
+    text = re.sub(
+        r"\n*---COMMIT_MESSAGE_START---\s*\n.*?\n---COMMIT_MESSAGE_END---\s*",
+        "",
+        text,
+        flags=re.DOTALL,
+    )
+    # Remove unified diff markers and content
+    text = re.sub(
+        r"\n*---UNIFIED_DIFF_START---\s*\n.*?\n---UNIFIED_DIFF_END---\s*",
+        "",
+        text,
+        flags=re.DOTALL,
+    )
+    return text.strip()
+
+
+def send_email(
+    to_addrs: list[str],
+    cc_addrs: list[str],
+    from_addr: str,
+    subject: str,
+    in_reply_to: str | None,
+    body: str,
+    dry_run: bool = False,
+    verbose: bool = False,
+) -> None:
+    """Send review email via SMTP using git sendemail config."""
+    # Build email message
+    msg = EmailMessage()
+    msg["From"] = from_addr
+    msg["To"] = ", ".join(to_addrs)
+    if cc_addrs:
+        msg["Cc"] = ", ".join(cc_addrs)
+    msg["Subject"] = subject
+    if in_reply_to:
+        msg["In-Reply-To"] = in_reply_to
+        msg["References"] = in_reply_to
+    msg.set_content(body)
+
+    if dry_run:
+        print("=== Email Preview (dry-run) ===", file=sys.stderr)
+        print(msg.as_string(), file=sys.stderr)
+        print("=== End Preview ===", file=sys.stderr)
+        return
+
+    # Get SMTP configuration from git config
+    smtp_config = get_smtp_config()
+
+    if not smtp_config["server"]:
+        error("No SMTP server configured. Set git config sendemail.smtpserver")
+
+    server = smtp_config["server"]
+    port = smtp_config["port"]
+    user = smtp_config["user"]
+    encryption = smtp_config["encryption"]
+
+    # Get password from environment or git config, or prompt
+    password = os.environ.get("SMTP_PASSWORD") or smtp_config["password"]
+    if user and not password:
+        password = getpass.getpass(f"SMTP password for {user}@{server}: ")
+
+    if verbose:
+        print(f"SMTP server: {server}:{port}", file=sys.stderr)
+        print(f"SMTP user: {user or '(none)'}", file=sys.stderr)
+        print(f"Encryption: {encryption or 'starttls'}", file=sys.stderr)
+
+    # Collect all recipients
+    all_recipients = list(to_addrs)
+    if cc_addrs:
+        all_recipients.extend(cc_addrs)
+
+    try:
+        if encryption == "ssl":
+            # SSL/TLS connection from the start (port 465)
+            context = ssl.create_default_context()
+            with smtplib.SMTP_SSL(server, port, context=context) as smtp:
+                if user and password:
+                    smtp.login(user, password)
+                smtp.send_message(msg, from_addr, all_recipients)
+        else:
+            # STARTTLS (port 587) or plain (port 25)
+            with smtplib.SMTP(server, port) as smtp:
+                smtp.ehlo()
+                if encryption == "tls" or port == 587:
+                    context = ssl.create_default_context()
+                    smtp.starttls(context=context)
+                    smtp.ehlo()
+                if user and password:
+                    smtp.login(user, password)
+                smtp.send_message(msg, from_addr, all_recipients)
+
+        print(f"Email sent via SMTP ({server}:{port})", file=sys.stderr)
+
+    except smtplib.SMTPAuthenticationError as e:
+        error(f"SMTP authentication failed: {e}")
+    except smtplib.SMTPException as e:
+        error(f"SMTP error: {e}")
+    except OSError as e:
+        error(f"Connection error to {server}:{port}: {e}")
+
+
+def list_providers() -> None:
+    """Print available providers and exit."""
+    print("Available AI Providers:\n")
+    print(f"{'Provider':<12} {'Default Model':<30} {'API Key Variable'}")
+    print(f"{'--------':<12} {'-------------':<30} {'----------------'}")
+    for name, config in PROVIDERS.items():
+        print(f"{name:<12} {config['default_model']:<30} {config['env_var']}")
+    sys.exit(0)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Review DPDK documentation files using AI providers. "
+        "Accepts multiple files and generates output for each.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    %(prog)s doc/guides/prog_guide/mempool_lib.rst
+    %(prog)s doc/guides/nics/*.rst              # Review all NIC docs
+    %(prog)s -p openai -o /tmp doc/guides/nics/ixgbe.rst doc/guides/nics/i40e.rst
+    %(prog)s -f html -d -o /tmp/reviews doc/guides/nics/*.rst  # HTML + diff files
+    %(prog)s -f json -o /tmp doc/guides/howto/flow_bifurcation.rst
+    %(prog)s --send-email --to [email protected] doc/guides/nics/ixgbe.rst
+
+Output files (in output-dir):
+    <basename>.txt|.md|.html|.json  Review in selected format
+    <basename>.diff                  Unified diff (text/json, or with --diff)
+    <basename>.msg                   Commit message (text/json, or with --diff)
+
+After review:
+    git apply <basename>.diff
+    git commit -sF <basename>.msg
+
+SMTP Configuration (from git config):
+    sendemail.smtpserver      SMTP server hostname
+    sendemail.smtpserverport  SMTP port (default: 587 for TLS, 465 for SSL)
+    sendemail.smtpuser        SMTP username
+    sendemail.smtpencryption  'tls' for STARTTLS, 'ssl' for SSL/TLS
+    sendemail.smtppass        SMTP password (or set SMTP_PASSWORD env var)
+
+Example git config:
+    git config --global sendemail.smtpserver smtp.gmail.com
+    git config --global sendemail.smtpserverport 587
+    git config --global sendemail.smtpuser [email protected]
+    git config --global sendemail.smtpencryption tls
+
+Token Usage:
+    Token counts are always printed to stderr after each run.
+        """,
+    )
+
+    parser.add_argument(
+        "doc_files",
+        nargs="+",
+        metavar="doc_file",
+        help="Documentation file(s) to review",
+    )
+    parser.add_argument(
+        "-p",
+        "--provider",
+        choices=PROVIDERS.keys(),
+        default="anthropic",
+        help="AI provider (default: anthropic)",
+    )
+    parser.add_argument(
+        "-a",
+        "--agents",
+        default="AGENTS.md",
+        help="Path to AGENTS.md file (default: AGENTS.md)",
+    )
+    parser.add_argument(
+        "-m",
+        "--model",
+        help="Model to use (default: provider-specific)",
+    )
+    parser.add_argument(
+        "-t",
+        "--tokens",
+        type=int,
+        default=8192,
+        help="Max tokens for response (default: 8192)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output-dir",
+        default=".",
+        help="Output directory for all output files (default: .)",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Show API request details",
+    )
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="Suppress review output to stdout (only write files)",
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        choices=FORMAT_EXTENSIONS,
+        default="text",
+        dest="output_format",
+        help="Output format: text, markdown, html, json (default: text)",
+    )
+    parser.add_argument(
+        "-d",
+        "--diff",
+        action="store_true",
+        help="Always produce .diff and .msg files (automatic for text/json)",
+    )
+    parser.add_argument(
+        "-l",
+        "--list-providers",
+        action="store_true",
+        help="List available providers and exit",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=120,
+        metavar="SECONDS",
+        help="API request timeout in seconds (default: 120)",
+    )
+
+    # Email options
+    email_group = parser.add_argument_group("Email Options")
+    email_group.add_argument(
+        "--send-email",
+        action="store_true",
+        help="Send review via email",
+    )
+    email_group.add_argument(
+        "--to",
+        action="append",
+        dest="to_addrs",
+        default=[],
+        metavar="ADDRESS",
+        help="Email recipient (can be specified multiple times)",
+    )
+    email_group.add_argument(
+        "--cc",
+        action="append",
+        dest="cc_addrs",
+        default=[],
+        metavar="ADDRESS",
+        help="CC recipient (can be specified multiple times)",
+    )
+    email_group.add_argument(
+        "--from",
+        dest="from_addr",
+        metavar="ADDRESS",
+        help="From address (default: from git config)",
+    )
+    email_group.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show email without sending",
+    )
+
+    args = parser.parse_args()
+
+    if args.list_providers:
+        list_providers()
+
+    # Get provider config
+    config = PROVIDERS[args.provider]
+    model = args.model or config["default_model"]
+
+    # Get API key
+    api_key = os.environ.get(config["env_var"])
+    if not api_key:
+        error(f"{config['env_var']} environment variable not set")
+
+    # Validate files
+    agents_path = Path(args.agents)
+    if not agents_path.exists():
+        error(f"AGENTS.md not found: {args.agents}")
+
+    # Validate all doc files exist before processing
+    doc_paths = []
+    for doc_file in args.doc_files:
+        doc_path = Path(doc_file)
+        if not doc_path.exists():
+            error(f"Documentation file not found: {doc_file}")
+        doc_paths.append((doc_file, doc_path))
+
+    # Validate email options
+    if args.send_email and not args.to_addrs:
+        error("--send-email requires at least one --to address")
+
+    # Get from address for email
+    from_addr = args.from_addr
+    if args.send_email and not from_addr:
+        git_name = get_git_config("user.name")
+        git_email = get_git_config("user.email")
+        if git_email:
+            from_addr = f"{git_name} <{git_email}>" if git_name else git_email
+        else:
+            error("No --from specified and git user.email not configured")
+
+    # Read AGENTS.md once
+    agents_content = agents_path.read_text()
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    provider_name = config["name"]
+
+    # Accumulate token usage across all API calls
+    total_usage = TokenUsage()
+
+    # Process each file
+    num_files = len(doc_paths)
+    for file_idx, (doc_file, doc_path) in enumerate(doc_paths, 1):
+        if num_files > 1:
+            print(
+                f"\n{'=' * 60}",
+                file=sys.stderr,
+            )
+            print(
+                f"Processing file {file_idx}/{num_files}: {doc_file}",
+                file=sys.stderr,
+            )
+            print(
+                f"{'=' * 60}",
+                file=sys.stderr,
+            )
+
+        # Determine output filenames
+        doc_basename = doc_path.stem
+        diff_file = output_dir / f"{doc_basename}.diff"
+        msg_file = output_dir / f"{doc_basename}.msg"
+
+        # Get commit prefix
+        commit_prefix = get_commit_prefix(doc_file)
+
+        # Read doc content
+        doc_content = doc_path.read_text()
+
+        if args.verbose:
+            print("=== Request ===", file=sys.stderr)
+            print(f"Provider: {args.provider}", file=sys.stderr)
+            print(f"Model: {model}", file=sys.stderr)
+            print(f"Output format: {args.output_format}", file=sys.stderr)
+            print(f"AGENTS file: {args.agents}", file=sys.stderr)
+            print(f"Doc file: {doc_file}", file=sys.stderr)
+            print(f"Commit prefix: {commit_prefix}", file=sys.stderr)
+            print(f"Output dir: {args.output_dir}", file=sys.stderr)
+            if args.send_email:
+                print("Send email: yes", file=sys.stderr)
+                print(f"To: {', '.join(args.to_addrs)}", file=sys.stderr)
+                if args.cc_addrs:
+                    print(f"Cc: {', '.join(args.cc_addrs)}", file=sys.stderr)
+                print(f"From: {from_addr}", file=sys.stderr)
+            print("===============", file=sys.stderr)
+
+        # Call API
+        review_text, call_usage = call_api(
+            args.provider,
+            api_key,
+            model,
+            args.tokens,
+            agents_content,
+            doc_content,
+            doc_file,
+            commit_prefix,
+            args.output_format,
+            args.diff,
+            args.verbose,
+            args.timeout,
+        )
+        total_usage.add(call_usage)
+
+        if not review_text:
+            print(
+                f"Warning: No response received for {doc_file}",
+                file=sys.stderr,
+            )
+            continue
+
+        # Determine review output file
+        format_ext = FORMAT_EXTENSIONS[args.output_format]
+        review_file = output_dir / f"{doc_basename}{format_ext}"
+
+        # Determine if we should write diff/msg files
+        write_diff_msg = args.diff or args.output_format in ("text", "json")
+
+        # Extract commit message and diff first (before stripping markers)
+        commit_msg, diff = "", ""
+        if write_diff_msg:
+            if args.output_format == "json":
+                # Will extract from JSON below
+                pass
+            else:
+                # Parse from text format markers
+                commit_msg, diff = parse_review_text(review_text)
+
+        # For non-text formats with --diff, strip the markers from display output
+        display_text = review_text
+        if args.diff and args.output_format in ("markdown", "html"):
+            display_text = strip_diff_markers(review_text)
+
+        # Build formatted output text
+        if args.output_format == "text":
+            output_text = review_text
+        elif args.output_format == "json":
+            # Try to parse JSON response
+            try:
+                review_data = json.loads(review_text)
+            except json.JSONDecodeError:
+                print("Warning: Response is not valid JSON", file=sys.stderr)
+                review_data = {"raw_response": review_text}
+
+            # Extract diff/msg from JSON if present
+            if write_diff_msg:
+                if isinstance(review_data, dict) and "raw_response" not in review_data:
+                    commit_msg = review_data.get("commit_message", "")
+                    diff = review_data.get("diff", "")
+
+            # Add metadata
+            usage_data = {
+                "api_calls": call_usage.api_calls,
+                "input_tokens": call_usage.input_tokens,
+                "output_tokens": call_usage.output_tokens,
+                "total_tokens": call_usage.input_tokens + call_usage.output_tokens,
+            }
+            if call_usage.cache_creation_tokens:
+                usage_data["cache_creation_tokens"] = call_usage.cache_creation_tokens
+            if call_usage.cache_read_tokens:
+                usage_data["cache_read_tokens"] = call_usage.cache_read_tokens
+
+            output_data = {
+                "metadata": {
+                    "doc_file": doc_file,
+                    "provider": args.provider,
+                    "provider_name": provider_name,
+                    "model": model,
+                    "commit_prefix": commit_prefix,
+                    "token_usage": usage_data,
+                },
+                "review": review_data,
+            }
+            output_text = json.dumps(output_data, indent=2)
+        elif args.output_format == "markdown":
+            output_text = f"""# Documentation Review: {doc_path.name}
+
+*Reviewed by {provider_name} ({model})*
+
+{display_text}
+"""
+        elif args.output_format == "html":
+            output_text = f"""<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>Review: {doc_path.name}</title>
+<style>
+body {{ font-family: system-ui, sans-serif; max-width: 900px; margin: 2em auto; padding: 0 1em; }}
+h1 {{ color: #333; }}
+.review-meta {{ color: #666; font-style: italic; }}
+pre {{ background: #f5f5f5; padding: 1em; overflow-x: auto; }}
+</style>
+</head>
+<body>
+<h1>Documentation Review: {doc_path.name}</h1>
+<p class="review-meta">Reviewed by {provider_name} ({model})</p>
+<div class="review-content">
+{display_text}
+</div>
+</body>
+</html>
+"""
+
+        # Write formatted review to file
+        review_file.write_text(output_text)
+        print(f"Review written to: {review_file}", file=sys.stderr)
+
+        # Write diff/msg files
+        if write_diff_msg:
+            if commit_msg:
+                msg_file.write_text(commit_msg + "\n")
+                print(f"Commit message written to: {msg_file}", file=sys.stderr)
+            else:
+                msg_file.write_text("# No commit message generated\n")
+                print("Warning: Could not extract commit message", file=sys.stderr)
+
+            if diff:
+                diff_file.write_text(diff + "\n")
+                print(f"Diff written to: {diff_file}", file=sys.stderr)
+            else:
+                diff_file.write_text("# No changes suggested\n")
+                print("Warning: Could not extract diff", file=sys.stderr)
+
+        # Print to stdout unless quiet (or multiple files without verbose)
+        show_stdout = not args.quiet and (num_files == 1 or args.verbose)
+        if show_stdout:
+            print(
+                f"\n=== Documentation Review: {doc_path.name} "
+                f"(via {provider_name}) ==="
+            )
+            print(output_text)
+
+            # Print usage instructions for text format
+            if args.output_format == "text":
+                print("\n=== Output Files ===")
+                print(f"Commit message: {msg_file}")
+                print(f"Diff file:      {diff_file}")
+                print("\nTo apply changes:")
+                print(f"  git apply {diff_file}")
+                print(f"  git commit -sF {msg_file}")
+
+        # Send email if requested
+        if args.send_email:
+            if args.output_format != "text":
+                print(
+                    f"Note: Email will be sent as plain text regardless of "
+                    f"--format={args.output_format}",
+                    file=sys.stderr,
+                )
+
+            review_subject = f"[REVIEW] {commit_prefix} {doc_path.name}"
+
+            # Build email body
+            email_body = f"""AI-generated documentation review of {doc_file}
+Reviewed using {provider_name} ({model})
+
+This is an automated review. Please verify all suggestions.
+
+---
+
+{review_text}
+"""
+
+            if args.verbose:
+                print("", file=sys.stderr)
+                print("=== Email Details ===", file=sys.stderr)
+                print(f"Subject: {review_subject}", file=sys.stderr)
+                print("=====================", file=sys.stderr)
+
+            send_email(
+                args.to_addrs,
+                args.cc_addrs,
+                from_addr,
+                review_subject,
+                None,
+                email_body,
+                args.dry_run,
+                args.verbose,
+            )
+
+            if not args.dry_run:
+                print("", file=sys.stderr)
+                print(f"Review sent to: {', '.join(args.to_addrs)}", file=sys.stderr)
+
+    # Print summary for multiple files
+    if num_files > 1:
+        print(f"\n{'=' * 60}", file=sys.stderr)
+        print(f"Processed {num_files} files", file=sys.stderr)
+        print(f"Output directory: {output_dir}", file=sys.stderr)
+
+    # Print token usage summary
+    if total_usage.api_calls > 0:
+        print("", file=sys.stderr)
+        print(
+            format_token_summary(total_usage, args.provider, model),
+            file=sys.stderr,
+        )
+
+
+if __name__ == "__main__":
+    main()

index 555e875329..6c0d356cfd 100644
@@ -210,3 +210,5 @@ Be sure to run the following test tools per patch in a patch series:
 * `check-doc-vs-code.sh`
 * `check-spdx-tag.sh`
 * Build documentation and validate how output looks
+* Optionally run ``analyze-patch.py`` for AI-assisted review
+  (see :ref:`ai_assisted_review` in the Contributing Guide)

71 lines not on this page · raw message

index 0f5539f851..c052b6c203 100644
@@ -109,6 +109,14 @@ F: license/
 F: .editorconfig
 F: .mailmap
 
+AI review tools
+M: Stephen Hemminger <[email protected]>
+M: Aaron Conole <[email protected]>
+F: AGENTS.md
+F: devtools/analyze-patch.py
+F: devtools/compare-reviews.sh
+F: devtools/review-doc.py
+
 Linux kernel uAPI headers
 M: Maxime Coquelin <[email protected]>
 F: devtools/linux-uapi.sh

index 060b26ff61..aa9e1e962c 100644
@@ -55,6 +55,11 @@ New Features
      Also, make sure to start the actual text at the margin.
      =======================================================
 
+* **Added scripts and prompts for AI review.**
+
+  Added AGENTS.md file for AI review and supporting scripts to analyze
+  patches and review documentation.
+
 
 Removed Items
 -------------

new file mode 100644
index 0000000000..8401f11c39
@@ -0,0 +1,1826 @@
+<!-- SPDX-License-Identifier: BSD-3-Clause -->
+<!-- Copyright(c) 2026 Stephen Hemminger -->
+
+# AGENTS.md - DPDK Code Review Guidelines for AI Tools
+
+## CRITICAL INSTRUCTION - READ FIRST
+
+This document has two categories of review rules with different confidence thresholds:
+
+### 1. Correctness Bugs -- HIGHEST PRIORITY (report at >=50% confidence)
+
+**Always report potential correctness bugs.** These are the most valuable findings.
+When in doubt, report them with a note about your confidence level.
+A possible use-after-free or resource leak is worth mentioning even if you are not certain.
+
+Correctness bugs include:
+- Use-after-free (accessing memory after `free`/`rte_free`)
+- Resource leaks on error paths (memory, file descriptors, locks)
+- Double-free or double-close
+- NULL pointer dereference
+- Buffer overflows or out-of-bounds access
+- Uninitialized variable use in a reachable code path
+- Race conditions (unsynchronized shared state)
+- `volatile` used instead of atomic operations for inter-thread shared variables
+- Missing error checks on functions that can fail
+- Error paths that skip cleanup (goto labels, missing free/close)
+- Incorrect error propagation (wrong return value, lost errno)
+- Logic errors in conditionals (wrong operator, inverted test)
+- Integer overflow/truncation in size calculations
+- Missing bounds checks on user-supplied sizes or indices
+- Statistics accumulation using `=` instead of `+=`
+- Integer multiply without widening cast losing upper bits (16x16, 32x32, etc.)
+- Unbounded descriptor chain traversal on guest/API-supplied data
+- `1 << n` on 64-bit bitmask (must use `1ULL << n` or `RTE_BIT64()`)
+- Left shift of narrow unsigned (`uint8_t`/`uint16_t`) used as 64-bit value (sign extension via implicit `int` promotion)
+- Variable assigned then overwritten before being read (dead store)
+- Same variable used as loop counter in nested loops
+- `rte_mbuf_raw_free_bulk()` called on mbufs that may originate from different mempools (Tx burst, ring dequeue)
+- MTU confused with frame length (MTU is L3 payload; frame length = MTU + L2 overhead)
+- Using `dev_conf.rxmode.mtu` after configure instead of `dev->data->mtu`
+- Hardcoded Ethernet overhead instead of per-device calculation
+- MTU set without enabling `RTE_ETH_RX_OFFLOAD_SCATTER` when frame size exceeds mbuf data room
+- `mtu_set` callback rejects valid MTU when scatter Rx is already enabled
+- Rx queue setup silently drops oversized packets instead of enabling scatter or returning an error
+- Rx function selection ignores `scattered_rx` flag or MTU-vs-mbuf-size check
+
+**Do NOT self-censor correctness bugs.** If you identify a code path
+where a resource could leak or memory could be used after free, report it.
+Do not talk yourself out of it.
+
+### 2. Style, Process, and Formatting -- suppress false positives
+
+**NEVER list a style/process item under "Errors" or "Warnings" if you conclude it is correct.**
+
+Before outputting any style, formatting, or process error/warning, verify it is actually wrong.
+If your analysis concludes with phrases like "there's no issue here", "which is fine",
+"appears correct", "is acceptable", or "this is actually correct" -- then DO NOT INCLUDE IT IN YOUR OUTPUT AT ALL.
+Delete it.
+Omit it entirely.
+
+This suppression rule applies to: naming conventions, code style, and process compliance.
+It does NOT apply to correctness bugs listed above.
+(SPDX/copyright format and commit message formatting are handled by checkpatch
+and are excluded from AI review entirely.)
+
+---
+
+This document provides guidelines for AI-powered code review tools
+when reviewing contributions to the Data Plane Development Kit (DPDK).
+It is derived from the official DPDK contributor guidelines and validation scripts.
+
+## Overview
+
+DPDK follows a development process modeled on the Linux Kernel.
+All patches are reviewed publicly on the mailing list before being merged.
+AI review tools should verify compliance with the standards outlined below.
+
+## Review Philosophy
+
+**Correctness bugs are the primary goal of AI review.** Style and formatting checks are secondary.
+A review that catches a use-after-free but misses a style nit is far more valuable
+than one that catches every style issue but misses the bug.
+
+**BEFORE OUTPUTTING YOUR REVIEW**: Re-read each item.
+- For correctness bugs: keep them.
+  If you have reasonable doubt that a code path is safe, report it.
+- For style/process items: if ANY item contains phrases like "is fine", "no issue",
+  "appears correct", "is acceptable", "actually correct" -- DELETE THAT ITEM.
+  Do not include it.
+
+### Correctness review guidelines
+- Trace error paths: for every function that allocates a resource or acquires a lock,
+  verify that ALL error paths after that point release it
+- Check every `goto error` and early `return`: does it clean up everything allocated so far?
+- Look for use-after-free: after `free(p)`, is `p` accessed again?
+- Check that error codes are propagated, not silently dropped
+- Report at >=50% confidence; note uncertainty if appropriate
+- It is better to report a potential bug that turns out to be safe than to miss a real bug
+
+### Style and process review guidelines
+- Only comment on style/process issues when you have HIGH CONFIDENCE (>80%) that an issue exists
+- Be concise: one sentence per comment when possible
+- Focus on actionable feedback, not observations
+- When reviewing text, only comment on clarity issues if the text is genuinely confusing or could lead to errors.
+- Do NOT comment on copyright years, SPDX format, or copyright holders - not subject to AI review
+- Do NOT report an issue then contradict yourself - if something is acceptable, do not mention it at all
+- Do NOT include items in Errors/Warnings that you then say are "acceptable" or "correct"
+- Do NOT mention things that are correct or "not an issue" - only report actual problems
+- Do NOT speculate about contributor circumstances (employment, company policies, etc.)
+- Before adding any style item to your review, ask: "Is this actually wrong?"
+  If no, omit it entirely.
+- NEVER write "(Correction: ...)" - if you need to correct yourself, simply omit the item entirely
+- Do NOT add vague suggestions like "should be verified" or "should be checked" - either it's wrong
+  or don't mention it
+- Do NOT flag something as an Error then say "which is correct" in the same item
+- Do NOT say "no issue here" or "this is actually correct" - if there's no issue, do not include it in your review
+- Do NOT analyze cross-patch dependencies or compilation order - you cannot reliably determine this from patch review
+- Do NOT claim a patch "would cause compilation failure" based on symbols used in other patches in the series
+- Review each patch individually for its own correctness; assume the patch author ordered them correctly
+- When reviewing a patch series, OMIT patches that have no issues.
+  Do not include a patch in your output just to say "no issues found" or to summarize what the patch does.
+  Only include patches where you have actual findings to report.
+
+## Priority Areas (Review These)
+
+### Security & Safety
+- Unsafe code blocks without justification
+- Command injection risks (shell commands, user input)
+- Path traversal vulnerabilities
+- Credential exposure or hard coded secrets
+- Missing input validation on external data
+- Improper error handling that could leak sensitive info
+
+### Correctness Issues
+- Logic errors that could cause panics or incorrect behavior
+- Buffer overflows
+- Race conditions
+- **`volatile` for inter-thread synchronization**:
+  `volatile` does not provide atomicity or memory ordering between threads.
+  Use `rte_atomic_load_explicit()`/`rte_atomic_store_explicit()` with appropriate `rte_memory_order_*` instead.
+  See the Shared Variable Access section under Forbidden Tokens for details.
+- Resource leaks (files, connections, memory)
+- Off-by-one errors or boundary conditions
+- Incorrect error propagation
+- **Use-after-free** (any access to memory after it has been freed)
+- **Error path resource leaks**:
+  For every allocation or fd open,
+  trace each error path (`goto`, early `return`, conditional) to verify the resource is released.
+  Common patterns to check:
+  - `malloc`/`rte_malloc` followed by a failure that does `return -1` instead of `goto cleanup`
+  - `open()`/`socket()` fd not closed on a later error
+  - Lock acquired but not released on an error branch
+  - Partially initialized structure where early fields are allocated
+    but later allocation fails without freeing the early ones
+- **Double-free / double-close**:
+  resource freed in both a normal path and an error path, or fd closed but not set to -1 allowing a second close
+- **Missing error checks**:
+  functions that can fail (malloc, open, ioctl, etc.) whose return value is not checked
+- **Do NOT flag unchecked return values from functions
+  that always succeed on Linux.** Some POSIX functions are documented to always return zero on Linux
+  when called with valid arguments.
+  Flagging unchecked returns from these is a false positive.
+  The list includes:
+  - `pthread_mutex_init()`, `pthread_cond_init()`
+  - `pthread_cond_signal()`, `pthread_cond_broadcast()`, `pthread_cond_wait()`
+  - `pthread_condattr_init()`, `pthread_condattr_destroy()`
+  - `pthread_attr_init()`, `pthread_attr_destroy()`
+- Changes to API without release notes
+- Changes to ABI on non-LTS release
+- Usage of deprecated APIs when replacements exist
+- Overly defensive code that adds unnecessary checks
+- Unnecessary comments that just restate what the code already shows (remove them)
+- **Process-shared synchronization errors** (pthread mutexes in shared memory without `PTHREAD_PROCESS_SHARED`)
+- **Statistics accumulation using `=` instead of `+=`**:
+  When accumulating statistics (counters, byte totals, packet counts),
+  using `=` overwrites the running total with only the latest value.
+  This silently produces wrong results.
+  ```c
+  /* BAD - overwrites instead of accumulating */
+  stats->rx_packets = nb_rx;
+  stats->rx_bytes = total_bytes;
+
+  /* GOOD - accumulates over time */
+  stats->rx_packets += nb_rx;
+  stats->rx_bytes += total_bytes;
+  ```
+  Note: `=` is correct for gauge-type values (e.g., queue depth, link status) and for initial assignment.
+  Only flag when the context is clearly incremental accumulation (loop bodies, per-burst counters, callback tallies).
+- **Integer multiply without widening cast**:
+  When multiplying integers to produce a result wider than the operands (sizes, offsets, byte counts),
+  the multiplication is performed at the operand width and the upper bits are silently lost before the assignment.
+  This applies to any narrowing scenario: 16x16 assigned to a 32-bit variable,
+  32x32 assigned to a 64-bit variable, etc.
+  ```c
+  /* BAD - 32x32 overflows before widening to 64 */
+  uint64_t total_size = num_entries * entry_size;  /* both are uint32_t */
+  size_t offset = ring->idx * ring->desc_size;     /* 32x32 -> truncated */
+
+  /* BAD - 16x16 overflows before widening to 32 */
+  uint32_t byte_count = pkt_len * nb_segs;         /* both are uint16_t */
+
+  /* GOOD - widen before multiply */
+  uint64_t total_size = (uint64_t)num_entries * entry_size;
+  size_t offset = (size_t)ring->idx * ring->desc_size;
+  uint32_t byte_count = (uint32_t)pkt_len * nb_segs;
+  ```
+- **Unbounded descriptor chain traversal**:
+  When walking a chain of descriptors (virtio, DMA, NIC Rx/Tx rings) where the chain length
+  or next-index comes from guest memory or an untrusted API caller,
+  the traversal MUST have a bounds check or loop counter to prevent infinite loops
+  or out-of-bounds access from malicious/corrupt data.
+  ```c
+  /* BAD - guest controls desc[idx].next with no bound */
+  while (desc[idx].flags & VRING_DESC_F_NEXT) {
+      idx = desc[idx].next;          /* guest-supplied, unbounded */
+      process(desc[idx]);
+  }
+
+  /* GOOD - cap iterations to descriptor ring size */
+  for (i = 0; i < ring_size; i++) {
+      if (!(desc[idx].flags & VRING_DESC_F_NEXT))
+          break;
+      idx = desc[idx].next;
+      if (idx >= ring_size)          /* bounds check */
+          return -EINVAL;
+      process(desc[idx]);
+  }
+  ```
+  This applies to any chain/linked-list traversal where indices
+  or pointers originate from untrusted input (guest VMs, user-space callers, network packets).
+- **Bitmask shift using `1` instead of `1ULL` on 64-bit masks**:
+  The literal `1` is `int` (32 bits).
+  Shifting it by 32 or more is undefined behavior; shifting it by less than 32
+  but assigning to a `uint64_t` silently zeroes the upper 32 bits.
+  Use `1ULL << n`, `UINT64_C(1) << n`, or the DPDK `RTE_BIT64(n)` macro.
+  ```c
+  /* BAD - 1 is int, UB if n >= 32, wrong if result used as uint64_t */
+  uint64_t mask = 1 << bit_pos;
+  if (features & (1 << VIRTIO_NET_F_MRG_RXBUF))  /* bit 15 OK, bit 32+ UB */
+
+  /* GOOD */
+  uint64_t mask = UINT64_C(1) << bit_pos;
+  uint64_t mask = 1ULL << bit_pos;
+  uint64_t mask = RTE_BIT64(bit_pos);        /* preferred in DPDK */
+  if (features & RTE_BIT64(VIRTIO_NET_F_MRG_RXBUF))
+  ```
+  Note: `1U << n` is acceptable when the mask is known to be 32-bit (e.g., `uint32_t` register fields with `n < 32`).
+  Only flag when the result is stored in, compared against, or returned as a 64-bit type, or when `n` could be >= 32.
+- **Left shift of narrow unsigned type sign-extends to 64-bit**:
+  When a `uint8_t` or `uint16_t` value is left-shifted,
+  C integer promotion converts it to `int` (signed 32-bit) before the shift.
+  If the result has bit 31 set, implicit conversion to `uint64_t`, `size_t`,
+  or use in pointer arithmetic sign-extends the upper 32 bits to all-1s, producing a wrong address or value.
+  This is Coverity SIGN_EXTENSION.
+  The fix is to cast the narrow operand to an unsigned type at least as wide as the target before shifting.
+  ```c
+  /* BAD - uint16_t promotes to signed int, bit 31 may set,
+   * then sign-extends when converted to 64-bit for pointer math */
+  uint16_t idx = get_index();
+  void *addr = base + (idx << wqebb_shift);      /* SIGN_EXTENSION */
+  uint64_t off = (uint64_t)(idx << shift);        /* too late: shift already in int */
+
+  /* BAD - uint8_t shift with result used as size_t */
+  uint8_t page_order = get_order();
+  size_t size = page_order << PAGE_SHIFT;          /* promotes to int first */
+
+  /* GOOD - cast before shift */
+  void *addr = base + ((uint64_t)idx << wqebb_shift);
+  uint64_t off = (uint64_t)idx << shift;
+  size_t size = (size_t)page_order << PAGE_SHIFT;
+
+  /* GOOD - intermediate unsigned variable */
+  uint32_t offset = (uint32_t)idx << wqebb_shift;  /* OK if result fits 32 bits */
+  ```
+  Note: This is distinct from the `1 << n` pattern (where the literal `1` is the problem)
+  and from the integer-multiply pattern (where the operation is `*` not `<<`).
+  The mechanism is the same C integer promotion rule, but the code patterns and Coverity checker names differ.
+  Only flag when the shift result is used in a context wider than 32 bits (64-bit assignment,
+  pointer arithmetic, function argument expecting `uint64_t`/`size_t`).
+  A shift whose result is stored in a `uint32_t` or narrower variable is not affected.
+- **Variable overwrite before read (dead store)**:
+  A variable is assigned a value that is unconditionally overwritten before it is ever read.
+  This usually indicates a logic error (wrong variable name, missing `if`, copy-paste mistake)
+  or at minimum is dead code.
+  ```c
+  /* BAD - first assignment is never read */
+  ret = validate_input(cfg);
+  ret = apply_config(cfg);     /* overwrites without checking first ret */
+  if (ret != 0)
+      return ret;
+
+  /* GOOD - check each return value */
+  ret = validate_input(cfg);
+  if (ret != 0)
+      return ret;
+  ret = apply_config(cfg);
+  if (ret != 0)
+      return ret;
+  ```
+  Do NOT flag cases where the initial value is intentionally a default that may
+  or may not be overwritten (e.g., `int ret = 0;` followed by a conditional assignment).
+  Only flag unconditional overwrites where the first value can never be observed.
+- **Shared loop counter in nested loops**:
+  Using the same variable as the loop counter in both an outer
+  and inner loop causes the outer loop to malfunction because the inner loop modifies its counter.
+  ```c
+  /* BAD - inner loop clobbers outer loop counter */
+  int i;
+  for (i = 0; i < nb_queues; i++) {
+      setup_queue(i);
+      for (i = 0; i < nb_descs; i++)    /* BUG: reuses i */
+          init_desc(i);
+  }
+
+  /* GOOD - distinct loop counters */
+  for (int i = 0; i < nb_queues; i++) {
+      setup_queue(i);
+      for (int j = 0; j < nb_descs; j++)
+          init_desc(j);
+  }
+  ```
+- **`rte_mbuf_raw_free_bulk()` on mixed-pool mbuf arrays**:
+  Tx burst functions and ring/queue dequeue paths receive mbufs
+  that may originate from different mempools (applications are free to send mbufs from any pool).
+  `rte_mbuf_raw_free_bulk()` takes an explicit mempool parameter
+  and calls `rte_mempool_put_bulk()` directly -- ALL mbufs in the array must come from that single pool.
+  If mbufs come from different pools, they are returned to the wrong pool,
+  corrupting pool accounting and causing hard-to-debug failures.
+  Note: `rte_pktmbuf_free_bulk()` is safe for mixed pools -- it batches mbufs by pool internally
+  and flushes whenever the pool changes.
+  ```c
+  /* BAD - assumes all mbufs are from the same pool */
+  /* (in tx_burst completion or ring dequeue error path) */
+  rte_mbuf_raw_free_bulk(mp, mbufs, nb_mbufs);
+
+  /* GOOD - rte_pktmbuf_free_bulk handles mixed pools correctly */
+  rte_pktmbuf_free_bulk(mbufs, nb_mbufs);
+
+  /* GOOD - free individually (each mbuf returned to its own pool) */
+  for (i = 0; i < nb_mbufs; i++)
+      rte_pktmbuf_free(mbufs[i]);
+  ```
+  This applies to any path that frees mbufs submitted by the application: Tx completion,
+  Tx error cleanup, and ring/queue drain paths.
+  `rte_mbuf_raw_free_bulk()` is an optimization for the fast-free case (`RTE_ETH_TX_OFFLOAD_MBUF_FAST_FREE`)
+  where the application guarantees all mbufs come from a single pool with refcnt=1.
+- **MTU confused with Ethernet frame length**:
+  Maximum Transmission Unit (MTU) is the maximum L3 payload size (e.g., 1500 bytes for standard Ethernet).
+  The maximum Ethernet *frame length* includes L2 overhead:
+  Ethernet header (14 bytes) + optional VLAN tags (4 bytes each) + CRC (4 bytes).
+  The overhead varies per device depending on supported encapsulations (VLAN, QinQ, etc.).
+  Confusing MTU with frame length produces off-by-14-to-22-byte errors in packet size limits,
+  buffer sizing, and scattered Rx decisions.
+
+  **VLAN tag accounting:** The outer VLAN tag is L2 overhead
+  and does NOT count toward MTU (matching Linux and FreeBSD).
+  A 1522-byte single-tagged frame is valid at MTU 1500.
+  However, in QinQ the inner (customer) tag DOES consume MTU -- it is part of the customer frame.
+  So QinQ with MTU 1500 allows only 1496 bytes of L3 payload unless the port MTU is raised to 1504.
+
+  **Using `rxmode.mtu` after configure:** After `rte_eth_dev_configure()` completes,
+  the canonical MTU is stored in `dev->data->mtu`.
+  The `dev->data->dev_conf.rxmode.mtu` field is the user's *request*
+  and must not be read after configure -- it becomes stale if `rte_eth_dev_set_mtu()` is called later.
+  Both configure and set_mtu write to `dev->data->mtu`; PMDs should always read from there.
+
+  **Overhead calculation:** Do not hardcode a single overhead constant.
+  Use the device's own overhead calculation (typically available via `dev_info.max_rx_pktlen - dev_info.max_mtu`
+  or an internal `eth_overhead` field).
+  Different devices support different encapsulations, so the overhead is not a universal constant.
+
+  **Scattered Rx decision:** PMDs compare maximum frame length (MTU + per-device overhead) against Rx buffer size to decide whether scattered Rx is needed.
+  Comparing raw MTU against buffer size is wrong -- it underestimates the actual frame size by the overhead.
+  ```c
+  /* BAD - MTU used where frame length is needed */
+  if (dev->data->mtu > rxq->buf_size)
+      enable_scattered_rx();
+
+  /* BAD - hardcoded overhead, wrong for QinQ-capable devices */
+  #define ETHER_OVERHEAD 18  /* may be 22 or 26 for VLAN/QinQ */
+  max_frame = mtu + ETHER_OVERHEAD;
+
+  /* BAD - reading rxmode.mtu after configure (stale if set_mtu called) */
+  static int
+  mydrv_rx_queue_setup(...) {
+      mtu = dev->data->dev_conf.rxmode.mtu;  /* WRONG - may be stale */
+      ...
+  }
+
+  /* GOOD - use dev->data->mtu, the canonical post-configure value */
+  static int
+  mydrv_rx_queue_setup(...) {
+      uint16_t mtu = dev->data->mtu;
+      ...
+  }
+
+  /* GOOD - use per-device overhead for frame length calculation */
+  uint32_t frame_overhead = dev_info.max_rx_pktlen - dev_info.max_mtu;
+  uint32_t max_frame_len = dev->data->mtu + frame_overhead;
+  if (max_frame_len > rxq->buf_size)
+      enable_scattered_rx();
+
+  /* GOOD - device-specific overhead constant derived from capabilities */
+  static uint32_t
+  mydrv_eth_overhead(struct rte_eth_dev *dev) {
+      uint32_t overhead = RTE_ETHER_HDR_LEN + RTE_ETHER_CRC_LEN;
+      if (dev->data->dev_conf.rxmode.offloads & RTE_ETH_RX_OFFLOAD_VLAN)
+          overhead += RTE_VLAN_HLEN;
+      if (dev->data->dev_conf.rxmode.offloads & RTE_ETH_RX_OFFLOAD_QINQ)
+          overhead += RTE_VLAN_HLEN;
+      return overhead;
+  }
+  ```
+  Note: In `rte_eth_dev_configure()` itself, reading `rxmode.mtu` is correct --
+  that is where the user's request is consumed and written to `dev->data->mtu`.
+  Only flag reads of `rxmode.mtu` *outside* configure (queue setup, start, link update, MTU set, etc.).
+- **Missing scatter Rx for large MTU**:
+  When the configured MTU produces a frame size (MTU + Ethernet overhead) larger
+  than the mbuf data buffer size (`rte_pktmbuf_data_room_size(mp) - RTE_PKTMBUF_HEADROOM`),
+  the PMD MUST either enable scatter Rx (multi-segment receive) or reject the configuration.
+  Silently accepting the MTU and then truncating or dropping oversized packets is a correctness bug.
+  ```c
+  /* BAD - accepts MTU but will truncate packets that don't fit */
+  static int
+  mydrv_mtu_set(struct rte_eth_dev *dev, uint16_t mtu)
+  {
+      /* No check against mbuf size or scatter capability */
+      dev->data->mtu = mtu;
+      return 0;
+  }
+
+  /* BAD - rejects valid MTU even though scatter is enabled */
+  if (frame_size > mbuf_data_size)
+      return -EINVAL;  /* wrong: should allow if scatter is on */
+
+  /* GOOD - check scatter and mbuf size */
+  if (!dev->data->scattered_rx &&
+      frame_size > dev->data->min_rx_buf_size - RTE_PKTMBUF_HEADROOM)
+      return -EINVAL;
+
+  /* GOOD - auto-enable scatter when needed */
+  if (frame_size > mbuf_data_size) {
+      if (!(dev_info.rx_offload_capa & RTE_ETH_RX_OFFLOAD_SCATTER))
+          return -EINVAL;
+      dev->data->dev_conf.rxmode.offloads |=
+          RTE_ETH_RX_OFFLOAD_SCATTER;
+      dev->data->scattered_rx = 1;
+  }
+  ```
+  Key relationships:
+  - `dev_info.max_rx_pktlen`: maximum frame the hardware can receive
+  - `dev_info.max_mtu`: maximum MTU = `max_rx_pktlen` - overhead
+  - `dev_info.min_rx_bufsize`: minimum Rx buffer the HW requires
+  - `dev_info.max_rx_bufsize`: maximum single-descriptor buffer size
+  - `mbuf data size = rte_pktmbuf_data_room_size(mp) - RTE_PKTMBUF_HEADROOM`
+  - When scatter is off: frame length must fit in a single mbuf
+  - When scatter is on: frame length can span multiple mbufs; the PMD selects a scattered Rx function
+
+  This pattern should be checked in three places:
+  1. `dev_configure()` -- validate MTU against mbuf size / scatter
+  2. `rx_queue_setup()` -- select scattered vs non-scattered Rx path
+  3. `mtu_set()` -- runtime MTU change must re-validate
+- **Rx queue function selection ignoring scatter**:
+  When a PMD has separate fast-path Rx functions for scalar (single-segment)
+  and scattered (multi-segment) modes,
+  it must select the scattered variant whenever `dev->data->scattered_rx` is set OR
+  when the configured frame length exceeds the single mbuf data size.
+  Failing to do so causes the scalar Rx function to silently drop or corrupt multi-segment packets.
+  ```c
+  /* BAD - only checks offload flag, ignores actual need */
+  if (rxmode->offloads & RTE_ETH_RX_OFFLOAD_SCATTER)
+      rx_func = mydrv_recv_scattered;
+  else
+      rx_func = mydrv_recv_single;  /* will drop oversized pkts */
+
+  /* GOOD - check both the flag and the size */
+  mbuf_size = rte_pktmbuf_data_room_size(rxq->mp) -
+              RTE_PKTMBUF_HEADROOM;
+  max_pkt = dev->data->mtu + overhead;
+  if ((rxmode->offloads & RTE_ETH_RX_OFFLOAD_SCATTER) ||
+      max_pkt > mbuf_size) {
+      dev->data->scattered_rx = 1;
+      rx_func = mydrv_recv_scattered;
+  } else {
+      rx_func = mydrv_recv_single;
+  }
+  ```
+
+### Architecture & Patterns
+- Code that violates existing patterns in the code base
+- Missing error handling
+- Code that is not safe against signals
+
+### New Library API Design
+
+When a patch adds a new library under `lib/`, review API design in addition to correctness and style.
+
+**API boundary.** A library should be a compiler, not a framework.
+The model is `rte_acl`: create a context, feed input, get structured output, caller decides what to do with it.
+No callbacks needed.
+If the library requires callers to implement a callback table to function,
+the boundary is wrong -- the library is asking the caller to be its backend.
+
+**Callback structs** (Warning / Error).
+Any function-pointer struct in an installed header is an ABI break waiting to happen.
+Adding or reordering a member breaks all consumers.
+- Prefer a single callback parameter over an ops table.
+- \>5 callbacks: **Warning** -- likely needs redesign.
+- \>20 callbacks: **Error** -- this is an app plugin API, not a library.
+- All callbacks must have Doxygen (contract, return values, ownership).
+- Void-returning callbacks for failable operations swallow errors -- flag as **Error**.
+- Callbacks serving app-specific needs (e.g. `verbose_level_get`) indicate wrong code was extracted into the library.
+
+**Extensible structures.** Prefer TLV / tagged-array patterns over enum + union,
+following `rte_flow_item` and `rte_flow_action` as the model.
+Type tag + pointer to type-specific data allows adding types without ABI breaks.
+Flag as **Warning**:
+- Large enums (100+) consumers must switch on.
+- Unions that grow with every new feature.
+- Ask: "What changes when a feature is added next release?"
+  If "add an enum value and union arm" -- should be TLV.
+
+**Installed headers.** If it's in `headers` or `indirect_headers` in meson.build, it's public API.
+Don't call it "private."
+If truly internal, don't install it.
+
+**Global state.** Prefer handle-based APIs (`create`/`destroy`) over singletons.
+`rte_acl` allows multiple independent classifier instances; new libraries should do the same.
+
+**Output ownership.** Prefer caller-allocated or library-allocated- caller-freed over internal static buffers.
+If static buffers are used, document lifetime and ensure Doxygen examples don't show stale-pointer usage.
+
+---
+
+## C Coding Style
+
+### General Formatting
+
+- **Tab width**:
+  8 characters (hard tabs for indentation, spaces for alignment)
+- **No trailing whitespace** on lines or at end of files
+- Files must end with a new line
+- Code style should be consistent within each file
+
+### Comments
+
+```c
+/* Most single-line comments look like this. */
+
+/*
+ * VERY important single-line comments look like this.
+ */
+
+/*
+ * Multi-line comments look like this. Make them real sentences. Fill
+ * them so they look like real paragraphs.
+ */
+```
+
+### Header File Organization
+
+Include order (each group separated by blank line):
+1. System/libc includes
+2. DPDK EAL includes
+3. DPDK misc library includes
+4. Application-specific includes
+
+```c
+#include <stdio.h>
+#include <stdlib.h>
+
+#include <rte_eal.h>
+
+#include <rte_ring.h>
+#include <rte_mempool.h>
+
+#include "application.h"
+```
+
+### Header Guards
+
+```c
+#ifndef _FILE_H_
+#define _FILE_H_
+
+/* Code */
+
+#endif /* _FILE_H_ */
+```
+
+### Naming Conventions
+
+- **All external symbols** must have `RTE_` or `rte_` prefix
+- **Macros**:
+  ALL_UPPERCASE with `RTE_` prefix
+- **Functions**:
+  lowercase with underscores only (no CamelCase)
+- **Variables**:
+  lowercase with underscores only
+- **Enum values**:
+  ALL_UPPERCASE with `RTE_<ENUM>_` prefix
+
+**Exception**: Driver base directories (`drivers/*/base/`) may use different naming conventions
+when sharing code across platforms or with upstream vendor code.
+
+#### Symbol Naming for Static Linking
+
+Drivers and libraries must not expose global variables that could clash
+when statically linked with other DPDK components or applications.
+Use consistent and unique prefixes for all exported symbols to avoid namespace collisions.
+
+**Good practice**: Use a driver-specific or library-specific prefix for all global variables:
+
+```c
+/* Good - virtio driver uses consistent "virtio_" prefix */
+const struct virtio_ops virtio_legacy_ops = {
+	.read = virtio_legacy_read,
+	.write = virtio_legacy_write,
+	.configure = virtio_legacy_configure,
+};
+
+const struct virtio_ops virtio_modern_ops = {
+	.read = virtio_modern_read,
+	.write = virtio_modern_write,
+	.configure = virtio_modern_configure,
+};
+
+/* Good - mlx5 driver uses consistent "mlx5_" prefix */
+struct mlx5_flow_driver_ops mlx5_flow_dv_ops;
+```
+
+**Bad practice**: Generic names that may clash:
+
+```c
+/* Bad - "ops" is too generic, will clash with other drivers */
+const struct virtio_ops ops = { ... };
+
+/* Bad - "legacy_ops" could clash with other legacy implementations */
+const struct virtio_ops legacy_ops = { ... };
+
+/* Bad - "driver_config" is not unique */
+struct driver_config config;
+```
+
+**Guidelines**:
+- Prefix all global variables with the driver or library name (e.g., `virtio_`, `mlx5_`, `ixgbe_`)
+- Prefix all global functions similarly unless they use the `rte_` namespace
+- Internal static variables do not require prefixes as they have file scope
+- Consider using the `RTE_` or `rte_` prefix only for symbols that are part of the public DPDK API
+
+#### Prohibited Terminology
+
+Do not use non-inclusive naming including:
+- `master/slave` -> Use: primary/secondary, controller/worker, leader/follower
+- `blacklist/whitelist` -> Use: denylist/allowlist, blocklist/passlist
+- `cripple` -> Use: impacted, degraded, restricted, immobilized
+- `tribe` -> Use: team, squad
+- `sanity check` -> Use: coherence check, test, verification
+
+
+### Comparisons and Boolean Logic
+
+DPDK style requires explicit comparison against `NULL`, `0`, or `'\0'` rather than
+truthiness on pointers, integers, and characters: write `if (p == NULL)` not `if (!p)`,
+and `if (a != 0)` not `if (a)`.
+Direct truthiness is acceptable only on actual `bool` types.
+`likely()` and `unlikely()` wrappers do not change whether a comparison is explicit
+(`if (likely(p != NULL))` is still explicit).
+
+Mechanical rewrites for these are handled by coccinelle in `devtools/cocci/`;
+AI review need only catch cases cocci can't see (e.g. macro-expanded conditions).
+
+### Boolean Usage
+
+Prefer `bool` (from `<stdbool.h>`) over `int` for variables, parameters,
+and return values that are purely true/false.
+Using `bool` makes intent explicit, enables compiler diagnostics for misuse, and is self-documenting.
+
+```c
+/* Bad - int used as boolean flag */
+int verbose = 0;
+int is_enabled = 1;
+
+int
+check_valid(struct item *item)
+{
+	if (item->flags & ITEM_VALID)
+		return 1;
+	return 0;
+}
+
+/* Good - bool communicates intent */
+bool verbose = false;
+bool is_enabled = true;
+
+bool
+check_valid(struct item *item)
+{
+	return item->flags & ITEM_VALID;
+}
+```
+
+**Guidelines:**
+- Use `bool` for variables that only hold true/false values
+- Use `bool` return type for predicate functions (functions that answer a yes/no question,
+  often named `is_*`, `has_*`, `can_*`)
+- Use `true`/`false` rather than `1`/`0` for boolean assignments
+- Boolean variables and parameters should not use explicit comparison:
+  `if (verbose)` is correct, not `if (verbose == true)`
+- `int` is still appropriate when a value can be negative, is an error code, or carries more than two states
+
+**Structure fields:**
+- `bool` occupies 1 byte.
+  In packed or cache-critical structures, consider using a bitfield or flags word instead
+- For configuration structures and non-hot-path data, `bool` is preferred over `int` for flag fields
+
+```c
+/* Bad - int flags waste space and obscure intent */
+struct port_config {
+	int promiscuous;     /* 0 or 1 */
+	int link_up;         /* 0 or 1 */
+	int autoneg;         /* 0 or 1 */
+	uint16_t mtu;
+};
+
+/* Good - bool for flag fields */
+struct port_config {
+	bool promiscuous;
+	bool link_up;
+	bool autoneg;
+	uint16_t mtu;
+};
+
+/* Also good - bitfield for cache-critical structures */
+struct fast_path_config {
+	uint32_t flags;      /* bitmask of CONFIG_F_* */
+	/* ... hot-path fields ... */
+};
+```
+
+**Do NOT flag:**
+- `int` return type for functions that return error codes (0 for success, negative for error) -- these are NOT boolean
+- `int` used for tri-state or multi-state values
+- `int` flags in existing code where changing the type would be a large, unrelated refactor
+- Bitfield or flags-word approaches in performance-critical structures
+
+### Indentation and Braces
+
+```c
+/* Control statements - no braces for single statements */
+if (val != NULL)
+	val = realloc(val, newsize);
+
+/* Braces on same line as else */
+if (test)
+	stmt;
+else if (bar) {
+	stmt;
+	stmt;
+} else
+	stmt;
+
+/* Switch statements - don't indent case */
+switch (ch) {
+case 'a':
+	aflag = 1;
+	/* FALLTHROUGH */
+case 'b':
+	bflag = 1;
+	break;
+default:
+	usage();
+}
+
+/* Long conditions - double indent continuation */
+if (really_long_variable_name_1 == really_long_variable_name_2 &&
+		really_long_variable_name_3 == really_long_variable_name_4)
+	stmt;
+```
+
+### Variable Declarations
+
+- Prefer declaring variables inside the basic block where they are used
+- Variables may be declared either at the start of the block, or at point of first use (C99 style)
+- Both declaration styles are acceptable; consistency within a function is preferred
+- Initialize variables only when a meaningful value exists at declaration time
+- Use C99 designated initializers for structures
+
+```c
+/* Good - declaration at start of block */
+int ret;
+ret = some_function();
+
+/* Also good - declaration at point of use (C99 style) */
+for (int i = 0; i < count; i++)
+	process(i);
+
+/* Good - declaration in inner block where variable is used */
+if (condition) {
+	int local_val = compute();
+	use(local_val);
+}
+
+/* Bad - unnecessary initialization defeats compiler warnings */
+int ret = 0;
+ret = some_function();    /* Compiler won't warn if assignment removed */
+```
+
+### Function Format
+
+- Return type on its own line
+- Opening brace on its own line
+- Place an empty line between declarations and statements
+
+```c
+static char *
+function(int a1, int b1)
+{
+	char *p;
+
+	p = do_something(a1, b1);
+	return p;
+}
+```
+
+---
+
+## Unnecessary Code Patterns
+
+The following patterns add unnecessary code, hide bugs, or reduce performance.
+Avoid them.
+Several closely related patterns are caught by coccinelle scripts in `devtools/cocci/`
+(unnecessary `void *` casts, NULL checks before `free()`/`rte_free()`,
+`memset()` before `free()`, zero-length array members, dead variable initialization);
+those are not duplicated here.
+
+### Appropriate Use of rte_malloc()
+
+`rte_malloc()` allocates from hugepage memory.
+Use it only when required:
+
+- Memory that will be accessed by DMA (NIC descriptors, packet buffers)
+- Memory shared between primary and secondary DPDK processes
+- Memory requiring specific NUMA node placement
+
+For general allocations, use standard `malloc()` which is faster and does not consume limited hugepage resources.
+
+Queue-related buffers (descriptor rings, Rx/Tx queue control structures) should use `rte_zmalloc_socket()` rather
+than plain `rte_malloc()`: zero-initialization avoids stale descriptor bugs,
+the `_socket` variant ensures NUMA-local allocation,
+and hugepage backing makes the memory visible to secondary processes.
+
+```c
+/* Bad - rte_malloc for ordinary data structure */
+struct config *cfg = rte_malloc(NULL, sizeof(*cfg), 0);
+
+/* Good - standard malloc for control structures */
+struct config *cfg = malloc(sizeof(*cfg));
+
+/* Good - rte_zmalloc_socket for descriptor rings / queue structures */
+struct my_rx_desc *ring = rte_zmalloc_socket("rx_ring",
+    n * sizeof(*ring), RTE_CACHE_LINE_SIZE, socket_id);
+```
+
+### Appropriate Use of rte_memcpy()
+
+`rte_memcpy()` is optimized for bulk data transfer in the fast path.
+For general use, standard `memcpy()` is preferred because:
+
+- Modern compilers optimize `memcpy()` effectively
+- `memcpy()` includes bounds checking with `_FORTIFY_SOURCE`
+- `memcpy()` handles small fixed-size copies efficiently
+
+```c
+/* Bad - rte_memcpy in control path */
+rte_memcpy(&config, &default_config, sizeof(config));
+
+/* Good - standard memcpy for control path */
+memcpy(&config, &default_config, sizeof(config));
+
+/* Good - rte_memcpy for packet data in fast path */
+rte_memcpy(rte_pktmbuf_mtod(m, void *), payload, len);
+```
+
+### Non-const Function Pointer Arrays
+
+Arrays of function pointers (ops tables, dispatch tables, callback arrays) should be declared `const`
+when their contents are fixed at compile time.
+A non-`const` function pointer array can be overwritten by bugs or exploits,
+and prevents the compiler from placing the table in read-only memory.
+
+```c
+/* Bad - mutable when it doesn't need to be */
+static rte_rx_burst_t rx_functions[] = {
+	rx_burst_scalar,
+	rx_burst_vec_avx2,
+	rx_burst_vec_avx512,
+};
+
+/* Good - immutable dispatch table */
+static const rte_rx_burst_t rx_functions[] = {
+	rx_burst_scalar,
+	rx_burst_vec_avx2,
+	rx_burst_vec_avx512,
+};
+```
+
+**Exceptions** (do NOT flag):
+- Arrays modified at runtime for CPU feature detection or capability probing (e.g.,
+  selecting a burst function based on `rte_cpu_get_flag_enabled()`)
+- Arrays containing mutable state (e.g., entries that are linked into lists)
+- Arrays populated dynamically via registration APIs
+- `dev_ops` or similar structures assigned per-device at init time
+
+Only flag when the array is fully initialized at declaration with constant values and never modified thereafter.
+
+---
+
+## Forbidden Tokens
+
+### Functions
+
+Forbidden function additions (`rte_panic()`, `rte_exit()`, `perror()`, `printf()`,
+`fprintf()`, `getenv()` in `lib/` and `drivers/`, with appropriate per-function
+exceptions for EAL, `examples/`, and `app/test/`) are caught by `devtools/checkpatches.sh`.
+
+### Atomics and Memory Barriers
+
+Substitutions from the deprecated atomic APIs to the C11 DPDK wrappers
+(`__atomic_*`/`__ATOMIC_*` -> `rte_atomic_*_explicit()`/`rte_memory_order_*`,
+`__sync_*` -> `rte_atomic_*`, `rte_smp_{r,w,}mb()` -> `rte_atomic_thread_fence()`,
+`rte_atomic{16,32,64}_*()` -> `rte_atomic_*_explicit()`)
+are handled by coccinelle scripts in `devtools/cocci/`.
+AI review only needs to flag conceptual misuse, covered in the sections below.
+
+#### Shared Variable Access: volatile vs Atomics
+
+Variables shared between threads or between a thread and a signal handler **must** use atomic operations.
+The C `volatile` keyword is NOT a substitute for atomics
+-- it prevents compiler optimization of accesses but provides no atomicity guarantees
+and no memory ordering between threads.
+On some architectures, `volatile` reads and writes may tear on unaligned or multi-word values.
+
+DPDK provides C11 atomic wrappers that are portable across all supported compilers and architectures.
+Always use these for shared state.
+
+**Reading shared variables:**
+
+```c
+/* BAD - volatile provides no atomicity or ordering guarantee */
+volatile int stop_flag;
+if (stop_flag)           /* data race, compiler/CPU can reorder */
+    return;
+
+/* BAD - direct access to shared variable without atomic */
+if (shared->running)     /* undefined behavior if another thread writes */
+    process();
+
+/* GOOD - DPDK C11 atomic wrapper */
+if (rte_atomic_load_explicit(&shared->stop_flag, rte_memory_order_acquire))
+    return;
+
+/* GOOD - relaxed is fine for statistics or polling a flag where
+ * you don't need to synchronize other memory accesses */
+count = rte_atomic_load_explicit(&shared->count, rte_memory_order_relaxed);
+```
+
+**Writing shared variables:**
+
+```c
+/* BAD - volatile write */
+volatile int *flag = &shared->ready;
+*flag = 1;
+
+/* GOOD - atomic store with appropriate ordering */
+rte_atomic_store_explicit(&shared->ready, 1, rte_memory_order_release);
+```
+
+**Read-modify-write operations:**
+
+```c
+/* BAD - not atomic even with volatile */
+volatile uint64_t *counter = &stats->packets;
+*counter += nb_rx;       /* TOCTOU: load, add, store is 3 operations */
+
+/* GOOD - atomic add */
+rte_atomic_fetch_add_explicit(&stats->packets, nb_rx,
+    rte_memory_order_relaxed);
+```
+
+#### Memory Ordering Guide
+
+Use the weakest ordering that is correct.
+Stronger ordering constrains hardware and compiler optimization unnecessarily.
+
+| DPDK Ordering | When to Use |
+|---------------|-------------|
+| `rte_memory_order_relaxed` | Statistics counters, polling flags where no other data depends on the value. Most common for simple counters. |
+| `rte_memory_order_acquire` | **Load** side of a flag/pointer that guards access to other shared data. Ensures subsequent reads see data published by the releasing thread. |
+| `rte_memory_order_release` | **Store** side of a flag/pointer that publishes shared data. Ensures all prior writes are visible to a thread that does an acquire load. |
+| `rte_memory_order_acq_rel` | Read-modify-write operations (e.g., `fetch_add`) that both consume and publish shared state in one operation. |
+| `rte_memory_order_seq_cst` | Rarely needed. Only when multiple independent atomic variables must be observed in a globally consistent total order. Avoid unless required. |
+
+**Common pattern -- producer/consumer flag:**
+
+```c
+/* Producer thread: fill buffer, then signal ready */
+fill_buffer(buf, data, len);
+rte_atomic_store_explicit(&shared->ready, 1, rte_memory_order_release);
+
+/* Consumer thread: wait for flag, then read buffer */
+while (!rte_atomic_load_explicit(&shared->ready, rte_memory_order_acquire))
+    rte_pause();
+process_buffer(buf, len);  /* guaranteed to see producer's writes */
+```
+
+**Common pattern -- statistics counter (no ordering needed):**
+
+```c
+rte_atomic_fetch_add_explicit(&port_stats->rx_packets, nb_rx,
+    rte_memory_order_relaxed);
+```
+
+#### Standalone Fences
+
+Prefer ordering on the atomic operation itself (acquire load, release store) over standalone fences.
+Standalone fences (`rte_atomic_thread_fence()`) are a blunt instrument
+that orders ALL memory accesses around the fence, not just the atomic variable you care about.
+
+```c
+/* Acceptable but less precise - standalone fence */
+rte_atomic_store_explicit(&shared->flag, 1, rte_memory_order_relaxed);
+rte_atomic_thread_fence(rte_memory_order_release);
+
+/* Preferred - ordering on the operation itself */
+rte_atomic_store_explicit(&shared->flag, 1, rte_memory_order_release);
+```
+
+Standalone fences are appropriate when synchronizing multiple non-atomic writes (e.g.,
+filling a structure before publishing a pointer to it) where annotating each write individually is impractical.
+
+#### When volatile Is Still Acceptable
+
+`volatile` remains correct for:
+- Memory-mapped I/O registers (hardware MMIO)
+- Variables shared with signal handlers in single-threaded contexts
+- Interaction with `setjmp`/`longjmp`
+
+`volatile` is NOT correct for:
+- Any variable accessed by multiple threads
+- Polling flags between lcores
+- Statistics counters updated from multiple threads
+- Flags set by one thread and read by another
+
+**Do NOT flag** `volatile` used for MMIO or hardware register access (common in drivers under `drivers/*/base/`).
+
+### Threading
+
+Substitutions from `pthread_*()` to the DPDK `rte_thread_*()` wrappers,
+and from `rte_thread_set_name()`/`rte_thread_create_control()` to their
+`_prefixed_name`/`_internal_control` replacements,
+are handled by coccinelle in `devtools/cocci/`.
+
+### Process-Shared Synchronization
+
+When placing synchronization primitives in shared memory (memory accessible by multiple processes,
+such as DPDK primary/secondary processes or `mmap`'d regions),
+they **must** be initialized with process-shared attributes.
+Failure to do so causes **undefined behavior** that may appear to work in testing
+but fail unpredictably in production.
+
+#### pthread Mutexes in Shared Memory
+
+**This is an error** - mutex in shared memory without `PTHREAD_PROCESS_SHARED`:
+
+```c
+/* BAD - undefined behavior when used across processes */
+struct shared_data {
+	pthread_mutex_t lock;
+	int counter;
+};
+
+void init_shared(struct shared_data *shm) {
+	pthread_mutex_init(&shm->lock, NULL);  /* ERROR: missing pshared attribute */
+}
+```
+
+**Correct implementation**:
+
+```c
+/* GOOD - properly initialized for cross-process use */
+struct shared_data {
+	pthread_mutex_t lock;
+	int counter;
+};
+
+void init_shared(struct shared_data *shm) {
+	pthread_mutexattr_t attr;
+
+	pthread_mutexattr_init(&attr);
+	pthread_mutexattr_setpshared(&attr, PTHREAD_PROCESS_SHARED);
+	pthread_mutex_init(&shm->lock, &attr);
+	pthread_mutexattr_destroy(&attr);
+}
+```
+
+#### pthread Condition Variables in Shared Memory
+
+Condition variables also require the process-shared attribute:
+
+```c
+/* BAD - will not work correctly across processes */
+pthread_cond_init(&shm->cond, NULL);
+
+/* GOOD */
+pthread_condattr_t cattr;
+pthread_condattr_init(&cattr);
+pthread_condattr_setpshared(&cattr, PTHREAD_PROCESS_SHARED);
+pthread_cond_init(&shm->cond, &cattr);
+pthread_condattr_destroy(&cattr);
+```
+
+#### pthread Read-Write Locks in Shared Memory
+
+```c
+/* BAD */
+pthread_rwlock_init(&shm->rwlock, NULL);
+
+/* GOOD */
+pthread_rwlockattr_t rwattr;
+pthread_rwlockattr_init(&rwattr);
+pthread_rwlockattr_setpshared(&rwattr, PTHREAD_PROCESS_SHARED);
+pthread_rwlock_init(&shm->rwlock, &rwattr);
+pthread_rwlockattr_destroy(&rwattr);
+```
+
+#### When to Flag This Issue
+
+Flag as an **Error** when ALL of the following are true:
+1. A `pthread_mutex_t`, `pthread_cond_t`, `pthread_rwlock_t`, or `pthread_barrier_t` is initialized
+2. The primitive is stored in shared memory (identified by context such as:
+   structure in `rte_malloc`/`rte_memzone`, `mmap`'d memory, memory passed to secondary processes,
+   or structures documented as shared)
+3. The initialization uses `NULL` attributes or attributes without `PTHREAD_PROCESS_SHARED`
+
+**Do NOT flag** when:
+- The mutex is in thread-local or process-private heap memory (`malloc`)
+- The mutex is a local/static variable not in shared memory
+- The code already uses `pthread_mutexattr_setpshared()` with `PTHREAD_PROCESS_SHARED`
+- The synchronization uses DPDK primitives (`rte_spinlock_t`, `rte_rwlock_t`) which are designed for shared memory
+
+#### Preferred Alternatives
+
+For DPDK code, prefer DPDK's own synchronization primitives which are designed for shared memory:
+
+| pthread Primitive | DPDK Alternative |
+|-------------------|------------------|
+| `pthread_mutex_t` | `rte_spinlock_t` (busy-wait) or properly initialized pthread mutex |
+| `pthread_rwlock_t` | `rte_rwlock_t` |
+| `pthread_spinlock_t` | `rte_spinlock_t` |
+
+Note: `rte_spinlock_t` and `rte_rwlock_t` work correctly in shared memory without special initialization,
+but they are spinning locks unsuitable for long wait times.
+
+### Compiler Built-ins, Attributes, Format Specifiers, and Test Macros
+
+Mechanical substitutions handled by coccinelle in `devtools/cocci/`:
+`__attribute__` -> RTE macros in `rte_common.h` (except in `lib/eal/include/rte_common.h`);
+`__alignof__` -> C11 `alignof`; `__typeof__` -> `typeof`;
+`__builtin_*` -> EAL macros (except in `lib/eal/` and `drivers/*/base/`);
+`__reserved` identifier -> renamed (reserved in Windows headers);
+`%lld`/`%llu`/`%llx` -> `%PRId64`/`%PRIu64`/`%PRIx64`;
+`REGISTER_TEST_COMMAND` -> `REGISTER_<suite_name>_TEST`.
+
+Also avoid `#pragma` / `_Pragma` outside `rte_common.h`.
+
+### Headers and Build
+
+| Forbidden | Preferred | Context |
+|-----------|-----------|---------|
+| `#include <linux/pci_regs.h>` | `#include <rte_pci.h>` | |
+| `install_headers()` | Meson `headers` variable | meson.build |
+| `-DALLOW_EXPERIMENTAL_API` | Not in lib/drivers/app | Build flags |
+| `allow_experimental_apis` | Not in lib/drivers/app | Meson |
+| `#undef XXX` | `// XXX is not set` | config/rte_config.h |
+| Driver headers (`*_driver.h`, `*_pmd.h`) | Public API headers | app/, examples/ |
+
+### Documentation
+
+| Forbidden | Preferred |
+|-----------|-----------|
+| `http://...dpdk.org` | `https://...dpdk.org` |
+| `//doc.dpdk.org/guides/...` | `:ref:` or `:doc:` Sphinx references |
+| `::  file.svg` | `::  file.*` (wildcard extension) |
+
+---
+
+## Deprecated API Usage
+
+New patches must not introduce usage of deprecated APIs, macros, or functions.
+Deprecated items are marked with `RTE_DEPRECATED`
+or documented in the deprecation notices section of the release notes.
+
+### Rules for New Code
+
+- Do not call functions marked with `RTE_DEPRECATED` or `__rte_deprecated`
+- Do not use macros that have been superseded by newer alternatives
+- Do not use data structures or enum values marked as deprecated
+- Check `doc/guides/rel_notes/deprecation.rst` for planned deprecations
+- When a deprecated API has a replacement, use the replacement
+
+### Deprecating APIs
+
+A patch may mark an API as deprecated provided:
+
+- No remaining usages exist in the current DPDK codebase
+- The deprecation is documented in the release notes
+- A migration path or replacement API is documented
+- The `RTE_DEPRECATED` macro is used to generate compiler warnings
+
+```c
+/* Marking a function as deprecated */
+__rte_deprecated
+int
+rte_old_function(void);
+
+/* With a message pointing to the replacement */
+__rte_deprecated_msg("use rte_new_function() instead")
+int
+rte_old_function(void);
+```
+
+### Common Deprecated Patterns
+
+`rte_atomic*_t` types, `rte_smp_*mb()` barriers, and `pthread_*()` in portable code
+all have modern replacements covered in the Atomics and Threading sections above
+and are rewritten by coccinelle.
+
+When reviewing patches that add new code,
+flag any usage of deprecated APIs as requiring change to use the modern replacement.
+
+---
+
+## API Tag Requirements
+
+### `__rte_experimental`
+
+- Must appear **alone on the line** immediately preceding the return type
+- Only allowed in **header files** (not `.c` files)
+
+```c
+/* Correct */
+__rte_experimental
+int
+rte_new_feature(void);
+
+/* Wrong - not alone on line */
+__rte_experimental int rte_new_feature(void);
+
+/* Wrong - in .c file */
+```
+
+### `__rte_internal`
+
+- Must appear **alone on the line** immediately preceding the return type
+- Only allowed in **header files** (not `.c` files)
+
+```c
+/* Correct */
+__rte_internal
+int
+internal_function(void);
+```
+
+### Alignment Attributes
+
+`__rte_aligned`, `__rte_cache_aligned`, `__rte_cache_min_aligned` may only be used with `struct` or `union` types:
+
+```c
+/* Correct */
+struct __rte_cache_aligned my_struct {
+	/* ... */
+};
+
+/* Wrong */
+int __rte_cache_aligned my_variable;
+```
+
+### Packed Attributes
+
+- `__rte_packed_begin` must follow `struct`, `union`, or alignment attributes
+- `__rte_packed_begin` and `__rte_packed_end` must be used in pairs
+- Cannot use `__rte_packed_begin` with `enum`
+
+```c
+/* Correct */
+struct __rte_packed_begin my_packed_struct {
+	/* ... */
+} __rte_packed_end;
+
+/* Wrong - with enum */
+enum __rte_packed_begin my_enum {
+	/* ... */
+};
+```
+
+---
+
+## Code Quality Requirements
+
+### Compilation
+
+- Each commit must compile independently (for `git bisect`)
+- No forward dependencies within a patchset
+- Test with multiple targets, compilers, and options
+- Use `devtools/test-meson-builds.sh`
+
+**Note for AI reviewers**: You cannot verify compilation order or cross-patch dependencies from patch review alone.
+Do NOT flag patches claiming they "would fail to compile" based on symbols used in other patches in the series.
+Assume the patch author has ordered them correctly.
+
+### Testing
+
+- Add tests to `app/test` unit test framework
+- New API functions must be used in `/app` test directory
+- New device APIs require at least one driver implementation
+
+#### Functional Test Infrastructure
+
+Standalone functional tests should use the `TEST_ASSERT` macros
+and `unit_test_suite_runner` infrastructure for consistency and proper integration with the DPDK test framework.
+
+```c
+#include <rte_test.h>
+
+static int
+test_feature_basic(void)
+{
+	int ret;
+
+	ret = rte_feature_init();
+	TEST_ASSERT_SUCCESS(ret, "Failed to initialize feature");
+
+	ret = rte_feature_operation();
+	TEST_ASSERT_EQUAL(ret, 0, "Operation returned unexpected value");
+
+	TEST_ASSERT_NOT_NULL(rte_feature_get_ptr(),
+		"Feature pointer should not be NULL");
+
+	return TEST_SUCCESS;
+}
+
+static struct unit_test_suite feature_testsuite = {
+	.suite_name = "feature_autotest",
+	.setup = test_feature_setup,
+	.teardown = test_feature_teardown,
+	.unit_test_cases = {
+		TEST_CASE(test_feature_basic),
+		TEST_CASE(test_feature_advanced),
+		TEST_CASES_END()
+	}
+};
+
+static int
+test_feature(void)
+{
+	return unit_test_suite_runner(&feature_testsuite);
+}
+
+REGISTER_FAST_TEST(feature_autotest, NOHUGE_OK, ASAN_OK, test_feature);
+```
+
+The `REGISTER_FAST_TEST` macro parameters are:
+- Test name (e.g., `feature_autotest`)
+- `NOHUGE_OK` or `HUGEPAGES_REQUIRED` - whether test can run without hugepages
+- `ASAN_OK` or `ASAN_FAILS` - whether test is compatible with Address Sanitizer
+- Test function name
+
+Common `TEST_ASSERT` macros:
+- `TEST_ASSERT(cond, msg, ...)` - Assert condition is true
+- `TEST_ASSERT_SUCCESS(val, msg, ...)` - Assert value equals 0
+- `TEST_ASSERT_FAIL(val, msg, ...)` - Assert value is non-zero
+- `TEST_ASSERT_EQUAL(a, b, msg, ...)` - Assert two values are equal
+- `TEST_ASSERT_NOT_EQUAL(a, b, msg, ...)` - Assert two values differ
+- `TEST_ASSERT_NULL(val, msg, ...)` - Assert value is NULL
+- `TEST_ASSERT_NOT_NULL(val, msg, ...)` - Assert value is not NULL
+
+### Documentation
+
+- Add Doxygen comments for public APIs
+- Update release notes in `doc/guides/rel_notes/` for important changes
+- Code and documentation must be updated atomically in same patch
+- Only update the **current release** notes file
+- Documentation must match the code
+- PMD features must match the features matrix in `doc/guides/nics/features/`
+- Documentation must match device operations (see `doc/guides/nics/features.rst` for the mapping between features,
+  `eth_dev_ops`, and related APIs)
+- Release notes are NOT required for:
+  - Test-only changes (unit tests, functional tests)
+  - Internal APIs and helper functions (not exported to applications)
+  - Internal implementation changes that don't affect public API
+
+### RST Documentation Style
+
+When reviewing `.rst` documentation files, prefer **definition lists** over simple bullet lists
+where each item has a term and a description.
+Definition lists produce better-structured HTML/PDF output and are easier to scan.
+
+**When to suggest a definition list:**
+- A bullet list where each item starts with a bold or emphasized term followed by a dash, colon, or long explanation
+- Lists of options, parameters, configuration values, or features where each entry has a name and a description
+- Glossary-style enumerations
+
+**When a simple list is fine (do NOT flag):**
+- Short lists of items without descriptions (e.g., file names, steps)
+- Lists where items are single phrases or sentences with no term/definition structure
+- Enumerated steps in a procedure
+
+**RST definition list syntax:**
+
+```rst
+term 1
+   Description of term 1.
+
+term 2
+   Description of term 2.
+   Can span multiple lines.
+```
+
+**Example -- flag this pattern:**
+
+```rst
+* **error** - Fail with error (default)
+* **truncate** - Truncate content to fit token limit
+* **summary** - Request high-level summary review
+```
+
+**Suggest rewriting as:**
+
+```rst
+error
+   Fail with error (default).
+
+truncate
+   Truncate content to fit token limit.
+
+summary
+   Request high-level summary review.
+```
+
+This is a **Warning**-level suggestion, not an Error.
+Do not flag it when the existing list structure is appropriate (see "when a simple list is fine" above).
+
+### API and Driver Changes
+
+- New APIs must be marked as `__rte_experimental`
+- New APIs must have hooks in `app/testpmd` and tests in the functional test suite
+- Changes to existing APIs require release notes
+- New drivers or subsystems must have release notes
+- Internal APIs (used only within DPDK, not exported to applications) do NOT require release notes
+
+### ABI Compatibility and Symbol Exports
+
+**IMPORTANT**: DPDK uses automatic symbol map generation.
+Do **NOT** recommend manually editing `version.map` files - they are auto-generated from source code annotations.
+
+#### Symbol Export Macros
+
+New public functions must be annotated with export macros (defined in `rte_export.h`).
+Place the macro on the line immediately before the function definition in the `.c` file:
+
+```c
+/* For stable ABI symbols */
+RTE_EXPORT_SYMBOL(rte_foo_create)
+int
+rte_foo_create(struct rte_foo_config *config)
+{
+    /* ... */
+}
+
+/* For experimental symbols (include version when first added) */
+RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_foo_new_feature, 25.03)
+__rte_experimental
+int
+rte_foo_new_feature(void)
+{
+    /* ... */
+}
+
+/* For internal symbols (shared between DPDK components only) */
+RTE_EXPORT_INTERNAL_SYMBOL(rte_foo_internal_helper)
+int
+rte_foo_internal_helper(void)
+{
+    /* ... */
+}
+```
+
+#### Symbol Export Rules
+
+- `RTE_EXPORT_SYMBOL` - Use for stable ABI functions
+- `RTE_EXPORT_EXPERIMENTAL_SYMBOL(name, ver)` - Use for new experimental APIs (version is the DPDK release, e.g., `25.03`)
+- `RTE_EXPORT_INTERNAL_SYMBOL` - Use for functions shared between DPDK libs/drivers but not part of public API
+- Export macros go in `.c` files, not headers
+- The build system generates linker version maps automatically
+
+#### What NOT to Review
+
+- Do **NOT** flag missing `version.map` updates - maps are auto-generated
+- Do **NOT** suggest adding symbols to `lib/*/version.map` files
+
+#### ABI Versioning for Changed Functions
+
+When changing the signature of an existing stable function, use versioning macros from `rte_function_versioning.h`:
+
+- `RTE_VERSION_SYMBOL` - Create versioned symbol for backward compatibility
+- `RTE_DEFAULT_SYMBOL` - Mark the new default version
+
+Follow ABI policy and versioning guidelines in the contributor documentation.
+Enable ABI checks with `DPDK_ABI_REF_VERSION` environment variable.
+
+---
+
+## LTS (Long Term Stable) Release Review
+
+LTS releases are DPDK versions ending in `.11` (e.g., 23.11, 22.11, 21.11, 20.11, 19.11).
+When reviewing patches targeting an LTS branch, apply stricter criteria:
+
+### LTS-Specific Rules
+
+- **Only bug fixes allowed** -- no new features
+- **No new APIs** (experimental or stable)
+- **ABI must remain unchanged** -- no symbol additions, removals, or signature changes
+- Backported fixes should reference the original commit with a `Fixes:` tag
+- Copyright years should reflect when the code was originally written
+- Be conservative: reject changes that are not clearly bug fixes
+
+### What to Flag on LTS Branches
+
+**Error:**
+- New feature code (new functions, new driver capabilities)
+- New experimental or stable API additions
+- ABI changes (new or removed symbols, changed function signatures)
+- Changes that add new configuration options or parameters
+
+**Warning:**
+- Large refactoring that goes beyond what is needed for a fix
+- Missing `Fixes:` tag on a backported bug fix
+- Missing `Cc: [email protected]`
+
+### When LTS Rules Apply
+
+LTS rules apply when the reviewer is told the target release is an LTS version (via the `--release` option or equivalent).
+If no release is specified, assume the patch targets the main development branch
+where new features and APIs are allowed.
+
+---
+
+## Patch Validation Checklist
+
+### Commit Message and License
+
+Checked by `devtools/checkpatches.sh` -- not duplicated here.
+
+### Code Style
+
+- [ ] Lines <=100 characters
+- [ ] Hard tabs for indentation, spaces for alignment
+- [ ] No trailing whitespace
+- [ ] Proper include order
+- [ ] Header guards present
+- [ ] `rte_`/`RTE_` prefix on external symbols
+- [ ] Driver/library global variables use unique prefixes (e.g., `virtio_`, `mlx5_`)
+- [ ] No prohibited terminology
+- [ ] Proper brace style
+- [ ] Function return type on own line
+- [ ] No forbidden tokens (see table above)
+- [ ] No usage of deprecated APIs, macros, or functions
+- [ ] Process-shared primitives in shared memory use `PTHREAD_PROCESS_SHARED`
+- [ ] Statistics use `+=` not `=` for accumulation
+- [ ] Integer multiplies widened before operation when result is 64-bit
+- [ ] Descriptor chain traversals bounded by ring size or loop counter
+- [ ] 64-bit bitmasks use `1ULL <<` or `RTE_BIT64()`, not `1 <<`
+- [ ] Left shifts of `uint8_t`/`uint16_t` cast to unsigned target width before shift when result is 64-bit
+- [ ] No unconditional variable overwrites before read
+- [ ] Nested loops use distinct counter variables
+- [ ] `rte_mbuf_raw_free_bulk()` not used on mixed-pool mbuf arrays (Tx paths, ring dequeue, error paths)
+- [ ] MTU not confused with frame length (MTU = L3 payload, frame = MTU + L2 overhead)
+- [ ] PMDs read `dev->data->mtu` after configure, not `dev_conf.rxmode.mtu`
+- [ ] Ethernet overhead not hardcoded -- derived from device capabilities
+- [ ] Scatter Rx enabled or error returned when frame length exceeds single mbuf data size
+- [ ] `mtu_set` allows large MTU when scatter Rx is active; re-selects Rx burst function
+- [ ] Rx queue setup selects scattered Rx function when frame length exceeds mbuf
+- [ ] Static function pointer arrays declared `const` when contents are compile-time fixed
+- [ ] `bool` used for pure true/false variables, parameters, and predicate return types
+- [ ] Shared variables use `rte_atomic_*_explicit()`, not `volatile` or bare access
+- [ ] Memory ordering is the weakest correct choice (`relaxed` for counters, `acquire`/`release` for publish/consume)
+
+### API Tags
+
+- [ ] `__rte_experimental` alone on line, only in headers
+- [ ] `__rte_internal` alone on line, only in headers
+- [ ] Alignment attributes only on struct/union
+- [ ] Packed attributes properly paired
+- [ ] New public functions have `RTE_EXPORT_*` macro in `.c` file
+- [ ] Experimental functions use `RTE_EXPORT_EXPERIMENTAL_SYMBOL(name, version)`
+
+### Structure
+
+- [ ] Each commit compiles independently
+- [ ] Code and docs updated together
+- [ ] Documentation matches code behavior
+- [ ] RST docs use definition lists for term/description patterns
+- [ ] PMD features match `doc/guides/nics/features/` matrix
+- [ ] Device operations match documentation (per `features.rst` mappings)
+- [ ] Tests added/updated as needed
+- [ ] Functional tests use TEST_ASSERT macros and unit_test_suite_runner
+- [ ] New APIs marked as `__rte_experimental`
+- [ ] New APIs have testpmd hooks and functional tests
+- [ ] Current release notes updated for significant changes
+- [ ] Release notes updated for API changes
+- [ ] Release notes updated for new drivers or subsystems
+
+---
+
+## Meson Build Files
+
+### Style Requirements
+
+- 4-space indentation (no tabs)
+- Line continuations double-indented
+- Lists alphabetically ordered
+- Short lists (<=3 items): single line, no trailing comma
+- Long lists: one item per line, trailing comma on last item
+- No strict line length limit for meson files; lines under 100 characters are acceptable
+
+```python
+# Short list
+sources = files('file1.c', 'file2.c')
+
+# Long list
+headers = files(
+	'header1.h',
+	'header2.h',
+	'header3.h',
+)
+```
+
+---
+
+## Python Code
+
+- Must comply with formatting standards
+- Use **`black`** for code formatting validation
+- Line length acceptable up to 100 characters
+
+---
+
+## Validation Tools
+
+Run these before submitting:
+
+```bash
+# Check commit messages
+devtools/check-git-log.sh -n1
+
+# Check patch format and forbidden tokens
+devtools/checkpatches.sh -n1
+
+# Check maintainers coverage
+devtools/check-maintainers.sh
+
+# Build validation
+devtools/test-meson-builds.sh
+
+# Find maintainers for your patch
+devtools/get-maintainer.sh <patch-file>
+```
+
+---
+
+## Severity Levels for AI Review
+
+**Error** (must fix):
+
+*Correctness bugs (highest value findings):*
+- Use-after-free
+- Resource leaks on error paths (memory, file descriptors, locks)
+- Double-free or double-close
+- NULL pointer dereference on reachable code path
+- Buffer overflow or out-of-bounds access
+- Missing error check on a function that can fail, leading to undefined behavior
+- Race condition on shared mutable state without synchronization
+- `volatile` used instead of atomics for inter-thread shared variables
+- Error path that skips necessary cleanup
+- Statistics accumulation using `=` instead of `+=` (overwrite vs increment)
+- Integer multiply without widening cast losing upper bits (16x16, 32x32, etc.)
+- Unbounded descriptor chain traversal on guest/API-supplied indices
+- `1 << n` used for 64-bit bitmask (undefined behavior if n >= 32)
+- Left shift of `uint8_t`/`uint16_t` used in 64-bit context without widening cast (sign extension)
+- Variable assigned then unconditionally overwritten before read
+- Same variable used as counter in nested loops
+- `rte_mbuf_raw_free_bulk()` on mbuf array where mbufs may come from different pools (Tx burst, ring dequeue)
+- MTU used where frame length is needed or vice versa (off by L2 overhead)
+- `dev_conf.rxmode.mtu` read after configure instead of `dev->data->mtu` (stale value)
+- MTU accepted without scatter Rx when frame size exceeds single mbuf capacity (silent truncation/drop)
+- `mtu_set` rejects valid MTU when scatter Rx is already enabled
+- Rx function selection ignores `scattered_rx` flag or MTU-vs-mbuf-size comparison
+
+*Process and format errors:*
+- Forbidden tokens in code
+- `__rte_experimental`/`__rte_internal` in .c files or not alone on line
+- Compilation failures
+- ABI breaks without proper versioning
+- pthread mutex/cond/rwlock in shared memory without `PTHREAD_PROCESS_SHARED`
+
+*API design errors (new libraries only):*
+- Ops/callback struct with 20+ function pointers in an installed header
+- Callback struct members with no Doxygen documentation
+- Void-returning callbacks for failable operations (errors silently swallowed)
+
+**Warning** (should fix):
+- Missing Cc: [email protected] for fixes
+- Documentation gaps
+- Documentation does not match code behavior
+- PMD features missing from `doc/guides/nics/features/` matrix
+- Device operations not documented per `features.rst` mappings
+- Missing tests
+- Functional tests not using TEST_ASSERT macros or unit_test_suite_runner
+- New API not marked as `__rte_experimental`
+- New API without testpmd hooks or functional tests
+- New public function missing `RTE_EXPORT_*` macro
+- API changes without release notes
+- New drivers or subsystems without release notes
+- Inappropriate use of `rte_malloc()` or `rte_memcpy()`
+- Queue-related buffers (descriptor rings, Rx/Tx queue structures) allocated with `malloc()` instead of `rte_zmalloc_socket()` (breaks secondary process access, loses NUMA locality)
+- Driver/library global variables without unique prefixes (static linking clash risk)
+- Usage of deprecated APIs, macros, or functions in new code
+- RST documentation using bullet lists where definition lists would be more appropriate
+- Ops/callback struct with >5 function pointers in an installed header (ABI risk)
+- New API using fixed enum+union where TLV pattern would be more extensible
+- Installed header labeled "private" or "internal" in meson.build
+- New library using global singleton instead of handle-based API
+- Static function pointer array not declared `const` when contents are compile-time constant
+- `int` used instead of `bool` for variables or return values that are purely true/false
+- `rte_memory_order_seq_cst` used where weaker ordering (`relaxed`, `acquire`/`release`) suffices
+- Standalone `rte_atomic_thread_fence()` where ordering on the atomic operation itself would be clearer
+- Hardcoded Ethernet overhead constant instead of per-device overhead calculation
+- PMD does not advertise `RTE_ETH_RX_OFFLOAD_SCATTER` in `rx_offload_capa` but hardware supports multi-segment Rx
+- PMD `dev_info` reports `max_rx_pktlen` or `max_mtu` inconsistent with each other or with the Ethernet overhead
+- `mtu_set` callback does not re-select the Rx burst function after changing MTU
+
+**Do NOT flag** (common false positives):
+- Missing `version.map` updates (maps are auto-generated from `RTE_EXPORT_*` macros)
+- Suggesting manual edits to any `version.map` file
+- SPDX/copyright format, copyright years, copyright holders (not subject to AI review)
+- Commit message formatting (subject length, punctuation, tag order, case-sensitive terms) -- checked by checkpatch
+- Meson file lines under 100 characters
+- Anything you determine is correct (do not mention non-issues or say "No issue here")
+- `REGISTER_FAST_TEST` using `NOHUGE_OK`/`ASAN_OK` macros (this is the correct current format)
+- Missing release notes for test-only changes (unit tests do not require release notes)
+- Missing release notes for internal APIs or helper functions (only public APIs need release notes)
+- Any item you later correct with "(Correction: ...)" or "actually acceptable" - just omit it
+- Vague concerns ("should be verified", "should be checked") - if you're not sure it's wrong, don't flag it
+- Items where you say "which is correct" or "this is correct" - if it's correct, don't mention it at all
+- Items where you conclude "no issue here" or "this is actually correct" - omit these entirely
+- Clean patches in a series - do not include a patch just to say "no issues" or describe what it does
+- Cross-patch compilation dependencies - you cannot determine patch ordering correctness from review
+- Claims that a symbol "was removed in patch N" causing issues in patch M - assume author ordered correctly
+- Any speculation about whether patches will compile when applied in sequence
+- Mutexes/locks in process-private memory (standard `malloc`, stack, static non-shared) - these don't need `PTHREAD_PROCESS_SHARED`
+- Use of `rte_spinlock_t` or `rte_rwlock_t` in shared memory (these work correctly without special init)
+- `volatile` used for MMIO/hardware register access in drivers (this is correct usage)
+- Left shift of `uint8_t`/`uint16_t` where the result is stored in a `uint32_t`
+  or narrower variable and not used in pointer arithmetic or 64-bit context (sign extension cannot occur)
+- Reading `rxmode.mtu` inside `rte_eth_dev_configure()` implementation (that is where the user request is consumed)
+- `=` assignment to MTU or frame length fields during initial setup (only flag stale reads of `rxmode.mtu` outside configure)
+- PMDs that auto-enable scatter when MTU exceeds mbuf size (this is the correct pattern)
+- Hardcoded `RTE_ETHER_HDR_LEN + RTE_ETHER_CRC_LEN` as overhead when the PMD does not support VLAN
+  and device info is consistent
+- Tagged frames exceeding 1518 bytes at standard MTU
+  -- a single-tagged frame of 1522 bytes is valid at MTU 1500 (the outer VLAN header is L2 overhead, not payload).
+  Note: inner VLAN tags in QinQ *do* consume MTU; see the MTU section for details.
+
+**Info** (consider):
+- Minor style preferences
+- Optimization suggestions
+- Alternative approaches
+
+---
+
+# Response Format
+
+When you identify an issue:
+1. **State the problem** (1 sentence)
+2. **Why it matters** (1 sentence, only if not obvious)
+3. **Suggested fix** (code snippet or specific action)
+
+Example: This could panic if the string is NULL.
+
+---
+
+## FINAL CHECK BEFORE SUBMITTING REVIEW
+
+Before outputting your review, do two separate passes:
+
+### Pass 1: Verify correctness bugs are included
+
+Ask: "Did I trace every error path for resource leaks?
+Did I check for use-after-free?
+Did I verify error codes are propagated?"
+
+If you identified a potential correctness bug but talked yourself out of it, **add it back**.
+It is better to report a possible bug than to miss a real one.
+
+### Pass 2: Remove style/process false positives
+
+For EACH style/process item, ask: "Did I conclude this is actually fine/correct/acceptable/no issue?"
+
+If YES, DELETE THAT ITEM.
+It should not be in your output.
+
+An item that says "X is wrong... actually this is correct" is a FALSE POSITIVE and must be removed.
+This applies to style, format, and process items only.
+
+**If your Errors section would be empty after this check, that's fine -- it means the patches are good.**

new file mode 100644
index 0000000000..69982cbda5
@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2026 Stephen Hemminger
+
+"""Common utilities shared by the DPDK AI review scripts."""
+
+import argparse
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Any, NoReturn
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+# Provider configurations (model defaults; override with --model).
+PROVIDERS: dict[str, dict[str, str]] = {
+    "anthropic": {
+        "name": "Claude",
+        "endpoint": "https://api.anthropic.com/v1/messages",
+        "default_model": "claude-sonnet-4-5-20250929",
+        "env_var": "ANTHROPIC_API_KEY",
+    },
+    "openai": {
+        "name": "ChatGPT",
+        "endpoint": "https://api.openai.com/v1/chat/completions",
+        "default_model": "gpt-4.1",
+        "env_var": "OPENAI_API_KEY",
+    },
+    "xai": {
+        "name": "Grok",
+        "endpoint": "https://api.x.ai/v1/chat/completions",
+        "default_model": "grok-4-1-fast-non-reasoning",
+        "env_var": "XAI_API_KEY",
+    },
+    "google": {
+        "name": "Gemini",
+        "endpoint": "https://generativelanguage.googleapis.com/v1beta/models",
+        "default_model": "gemini-3-flash-preview",
+        "env_var": "GOOGLE_API_KEY",
+    },
+}
+
+
+def error(msg: str) -> NoReturn:
+    """Print error message to stderr and exit with status 1."""
+    print(f"Error: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def get_git_config(key: str) -> str | None:
+    """Return the value of a git config key, or None if unset/git missing."""
+    try:
+        result = subprocess.run(
+            ["git", "config", "--get", key],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+
+def list_providers() -> NoReturn:
+    """Print available providers and exit."""
+    print("Available AI Providers:\n")
+    print(f"{'Provider':<12} {'Default Model':<30} {'API Key Variable'}")
+    print(f"{'--------':<12} {'-------------':<30} {'----------------'}")
+    for name, config in PROVIDERS.items():
+        print(f"{name:<12} {config['default_model']:<30} {config['env_var']}")
+    sys.exit(0)
+
+
+@dataclass
+class TokenUsage:
+    """Accumulated token usage across API calls."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_creation_tokens: int = 0
+    cache_read_tokens: int = 0
+    api_calls: int = 0
+
+    def add(self, other: "TokenUsage") -> None:
+        """Accumulate usage from another TokenUsage."""
+        self.input_tokens += other.input_tokens
+        self.output_tokens += other.output_tokens
+        self.cache_creation_tokens += other.cache_creation_tokens
+        self.cache_read_tokens += other.cache_read_tokens
+        self.api_calls += other.api_calls
+
+
+def format_token_summary(usage: TokenUsage, provider: str, model: str) -> str:
+    """Format a token usage summary string."""
+    provider_label = PROVIDERS.get(provider, {}).get("name", provider)
+    lines = ["=== Token Usage Summary ==="]
+    lines.append(f"Provider:      {provider_label} ({model})")
+    lines.append(f"API calls:     {usage.api_calls}")
+    lines.append(f"Input tokens:  {usage.input_tokens:,}")
+    lines.append(f"Output tokens: {usage.output_tokens:,}")
+    if usage.cache_creation_tokens:
+        lines.append(f"Cache write:   {usage.cache_creation_tokens:,}")
+    if usage.cache_read_tokens:
+        lines.append(f"Cache read:    {usage.cache_read_tokens:,}")
+    total = usage.input_tokens + usage.output_tokens
+    lines.append(f"Total tokens:  {total:,}")
+    lines.append("=" * 27)
+    return "\n".join(lines)
+
+
+def add_token_args(parser: argparse.ArgumentParser) -> None:
+    """Add the --show-tokens flag to an ArgumentParser."""
+    parser.add_argument(
+        "--show-tokens",
+        action="store_true",
+        help="Show token usage summary on stderr after the run",
+    )
+
+
+def print_token_summary(
+    usage: TokenUsage, provider: str, model: str, show: bool
+) -> None:
+    """Print token usage summary to stderr if requested and any calls were made."""
+    if not show or usage.api_calls == 0:
+        return
+    print("", file=sys.stderr)
+    print(format_token_summary(usage, provider, model), file=sys.stderr)
+
+
+def _build_request_meta(
+    provider: str, api_key: str, model: str
+) -> tuple[str, dict[str, str]]:
+    """Return (url, headers) for a provider request."""
+    config = PROVIDERS[provider]
+    if provider == "anthropic":
+        return config["endpoint"], {
+            "Content-Type": "application/json",
+            "x-api-key": api_key,
+            "anthropic-version": "2023-06-01",
+        }
+    if provider == "google":
+        url = f"{config['endpoint']}/{model}:generateContent?key={api_key}"
+        return url, {"Content-Type": "application/json"}
+    # openai, xai
+    return config["endpoint"], {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {api_key}",
+    }
+
+
+def _extract_usage(provider: str, result: dict[str, Any]) -> TokenUsage:
+    """Extract TokenUsage from a provider response."""
+    usage = TokenUsage(api_calls=1)
+    if provider == "anthropic":
+        raw = result.get("usage", {})
+        usage.input_tokens = raw.get("input_tokens", 0)
+        usage.output_tokens = raw.get("output_tokens", 0)
+        usage.cache_creation_tokens = raw.get("cache_creation_input_tokens", 0)
+        usage.cache_read_tokens = raw.get("cache_read_input_tokens", 0)
+    elif provider == "google":
+        raw = result.get("usageMetadata", {})
+        usage.input_tokens = raw.get("promptTokenCount", 0)
+        usage.output_tokens = raw.get("candidatesTokenCount", 0)
+    else:  # openai, xai
+        raw = result.get("usage", {})
+        usage.input_tokens = raw.get("prompt_tokens", 0)
+        usage.output_tokens = raw.get("completion_tokens", 0)
+        cache_details = raw.get("prompt_tokens_details", {})
+        if cache_details:
+            usage.cache_read_tokens = cache_details.get("cached_tokens", 0)
+    return usage
+
+
+def _extract_text(provider: str, result: dict[str, Any]) -> str:
+    """Extract response text from a provider response. Calls error() on failure."""
+    if "error" in result:
+        error(f"API error: {result['error'].get('message', result)}")
+    if provider == "anthropic":
+        content = result.get("content", [])
+        return "".join(
+            block.get("text", "") for block in content if block.get("type") == "text"
+        )
+    if provider == "google":
+        candidates = result.get("candidates", [])
+        if not candidates:
+            error("No response from Gemini")
+        parts = candidates[0].get("content", {}).get("parts", [])
+        return "".join(part.get("text", "") for part in parts)
+    # openai, xai
+    choices = result.get("choices", [])
+    if not choices:
+        error("No response from API")
+    return choices[0].get("message", {}).get("content", "")
+
+
+def _print_verbose_usage(usage: TokenUsage) -> None:
+    """Print per-call token details to stderr."""
+    print("=== Token Usage ===", file=sys.stderr)
+    print(f"Input tokens: {usage.input_tokens:,}", file=sys.stderr)
+    print(f"Output tokens: {usage.output_tokens:,}", file=sys.stderr)
+    if usage.cache_creation_tokens:
+        print(f"Cache creation: {usage.cache_creation_tokens:,}", file=sys.stderr)
+    if usage.cache_read_tokens:
+        print(f"Cache read: {usage.cache_read_tokens:,}", file=sys.stderr)
+    print("===================", file=sys.stderr)
+
+
+def send_request(
+    provider: str,
+    api_key: str,
+    model: str,
+    request_data: dict[str, Any],
+    *,
+    timeout: int = 120,
+    verbose: bool = False,
+) -> tuple[str, TokenUsage]:
+    """Send a prebuilt request to a provider and return (response_text, usage).
+
+    The caller assembles the provider-specific request body via its own
+    build_*_request helpers (the prompts differ per script). This function
+    handles transport, error reporting, and token-usage extraction.
+    """
+    url, headers = _build_request_meta(provider, api_key, model)
+    body = json.dumps(request_data).encode("utf-8")
+    req = Request(url, data=body, headers=headers)
+
+    try:
+        with urlopen(req, timeout=timeout) as response:
+            result = json.loads(response.read().decode("utf-8"))
+    except HTTPError as e:
+        error_body = e.read().decode("utf-8")
+        try:
+            error_data = json.loads(error_body)
+            error(f"API error: {error_data.get('error', error_body)}")
+        except json.JSONDecodeError:
+            error(f"API error ({e.code}): {error_body}")
+    except URLError as e:
+        if isinstance(e.reason, TimeoutError):
+            error(f"Request timed out after {timeout} seconds")
+        error(f"Connection error: {e.reason}")
+
+    usage = _extract_usage(provider, result)
+    if verbose:
+        _print_verbose_usage(usage)
+    return _extract_text(provider, result), usage

new file mode 100755
index 0000000000..89e6384f99
@@ -0,0 +1,1330 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2026 Stephen Hemminger
+
+"""
+Analyze DPDK patches using AI providers.
+
+Supported providers: Anthropic Claude, OpenAI ChatGPT, xAI Grok, Google Gemini
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from datetime import date
+from email.message import EmailMessage
+from pathlib import Path
+from typing import Any, Iterator
+
+from _common import (
+    PROVIDERS,
+    TokenUsage,
+    add_token_args,
+    error,
+    get_git_config,
+    list_providers,
+    print_token_summary,
+    send_request,
+)
+
+# Output formats
+OUTPUT_FORMATS = ["text", "markdown", "html", "json"]
+
+# Large file handling modes
+LARGE_FILE_MODES = ["error", "truncate", "chunk", "commits-only", "summary"]
+
+# Approximate characters per token (conservative: fewer chars = higher estimate)
+CHARS_PER_TOKEN = 3.5
+
+# Default token limits by provider (leaving room for system prompt and response)
+PROVIDER_INPUT_LIMITS = {
+    "anthropic": 180000,  # 200K context, reserve for system/response
+    "openai": 900000,  # GPT-4.1 has 1M context
+    "xai": 1800000,  # Grok 4.1 Fast has 2M context
+    "google": 900000,  # Gemini 3 Flash has 1M context
+}
+
+# LTS releases: any DPDK release with minor version .11
+# (e.g., 19.11, 20.11, 21.11, 22.11, 23.11, 24.11, 25.11, ...)
+
+SYSTEM_PROMPT_BASE = """\
+You are an expert DPDK code reviewer. Analyze patches for compliance with \
+DPDK coding standards and contribution guidelines. Provide clear, actionable \
+feedback organized by severity (Error, Warning, Info) as defined in the \
+guidelines."""
+
+LTS_RULES = """
+LTS (Long Term Stable) branch rules apply:
+- Only bug fixes allowed, no new features
+- No new APIs (experimental or stable)
+- ABI must remain unchanged
+- Backported fixes should reference the original commit with Fixes: tag
+- Copyright years should reflect when the code was originally written
+- Be conservative: reject changes that aren't clearly bug fixes"""
+
+FORMAT_INSTRUCTIONS = {
+    "text": """Provide your review in plain text format.""",
+    "markdown": """Provide your review in Markdown format with:
+- Headers (##) for each severity level (Errors, Warnings, Info)
+- Bullet points for individual issues
+- Code blocks (```) for code references
+- Bold (**) for emphasis on key points""",
+    "html": """Provide your review in HTML format with:
+- <h2> tags for each severity level (Errors, Warnings, Info)
+- <ul>/<li> for individual issues
+- <pre><code> for code references
+- <strong> for emphasis on key points
+- Use appropriate semantic HTML tags
+- Do NOT include <html>, <head>, or <body> tags - just the content""",
+    "json": """Provide your review in JSON format with this structure:
+{
+  "summary": "Brief one-line summary of the review",
+  "errors": [
+    {"issue": "description", "location": "file:line", "suggestion": "fix"}
+  ],
+  "warnings": [
+    {"issue": "description", "location": "file:line", "suggestion": "fix"}
+  ],
+  "info": [
+    {"issue": "description", "location": "file:line", "suggestion": "fix"}
+  ],
+  "passed_checks": ["list of checks that passed"],
+  "overall_status": "PASS|WARN|FAIL"
+}
+Output ONLY valid JSON, no markdown code fences or other text.""",
+}
+
+USER_PROMPT = """Please review the following DPDK patch file '{patch_name}' \
+against the AGENTS.md guidelines. Focus on:
+
+1. Correctness bugs (resource leaks, use-after-free, race conditions, etc.)
+2. C coding style (forbidden tokens, implicit comparisons, unnecessary patterns)
+3. API and documentation requirements
+4. Any other guideline violations
+
+Note: commit message formatting and SPDX/copyright compliance are checked \
+by checkpatches.sh and should NOT be flagged here.
+
+{format_instruction}
+
+--- PATCH CONTENT ---
+"""
+
+# Exit codes for review results
+EXIT_CLEAN = 0
+EXIT_WARNINGS = 2
+EXIT_ERRORS = 3
+
+
+def classify_review(review_text: str, output_format: str) -> int:
+    """Classify review result and return appropriate exit code.
+
+    Returns:
+        0 - clean (no errors or warnings)
+        2 - warnings found (no errors)
+        3 - errors found
+    """
+    has_errors = False
+    has_warnings = False
+
+    if output_format == "json":
+        try:
+            data = json.loads(review_text)
+            if data.get("errors"):
+                has_errors = True
+            if data.get("warnings"):
+                has_warnings = True
+            status = data.get("overall_status", "").upper()
+            if status == "FAIL":
+                has_errors = True
+            elif status == "WARN":
+                has_warnings = True
+        except (json.JSONDecodeError, AttributeError):
+            pass  # Fall through to text scanning
+
+    if not has_errors and not has_warnings:
+        # Scan review text for severity indicators.
+        # Match section headers and inline markers across text/markdown/html.
+        for line in review_text.splitlines():
+            stripped = line.strip().lower()
+            # Skip quoted patch context lines
+            if stripped.startswith(">") or stripped.startswith("diff --git"):
+                continue
+            if re.match(r"^(#{1,3}\s+)?(\*{0,2})error", stripped) or re.match(
+                r"^<h[1-3]>\s*error", stripped
+            ):
+                has_errors = True
+            elif re.match(r"^(#{1,3}\s+)?(\*{0,2})warning", stripped) or re.match(
+                r"^<h[1-3]>\s*warning", stripped
+            ):
+                has_warnings = True
+
+    if has_errors:
+        return EXIT_ERRORS
+    if has_warnings:
+        return EXIT_WARNINGS
+    return EXIT_CLEAN
+
+
+def is_lts_release(release: str | None) -> bool:
+    """Check if a release is an LTS release.
+
+    Per DPDK project guidelines, any release with minor version .11
+    is an LTS release (e.g., 19.11, 21.11, 23.11, 24.11, 25.11).
+    """
+    if not release:
+        return False
+    # Check for explicit -lts suffix
+    if "-lts" in release.lower():
+        return True
+    # Extract base version (e.g., "23.11" from "23.11.1" or "23.11-rc1")
+    version = release.split("-")[0]
+    parts = version.split(".")
+    if len(parts) >= 2:
+        try:
+            minor = int(parts[1])
+            return minor == 11
+        except ValueError:
+            pass
+    return False
+
+
+def estimate_tokens(text: str) -> int:
+    """Estimate token count from text length."""
+    return int(len(text) / CHARS_PER_TOKEN)
+
+
+def split_mbox_patches(content: str) -> list[str]:
+    """Split an mbox file into individual patches."""
+    patches = []
+    current_patch = []
+    in_patch = False
+
+    for line in content.split("\n"):
+        # Detect start of new message in mbox format
+        # git-format-patch: "From <40-char-hex> Mon Sep 17 00:00:00 2001"
+        # general mbox: "From <addr> <day-of-week> ..."
+        if line.startswith("From ") and (
+            re.match(r"^From [0-9a-f]{40} ", line)
+            or " Mon " in line
+            or " Tue " in line
+            or " Wed " in line
+            or " Thu " in line
+            or " Fri " in line
+            or " Sat " in line
+            or " Sun " in line
+        ):
+            if current_patch:
+                patches.append("\n".join(current_patch))
+            current_patch = [line]
+            in_patch = True
+        elif in_patch:
+            current_patch.append(line)
+
+    # Don't forget the last patch
+    if current_patch:
+        patches.append("\n".join(current_patch))
+
+    return patches if patches else [content]
+
+
+def extract_commit_messages(content: str) -> str:
+    """Extract only commit messages from patch content."""
+    patches = split_mbox_patches(content)
+    messages = []
+
+    for patch in patches:
+        lines = patch.split("\n")
+        msg_lines = []
+        in_headers = True
+        in_body = False
+        found_subject = False
+
+        for line in lines:
+            # Collect headers we care about
+            if in_headers:
+                if line.startswith("Subject:"):
+                    msg_lines.append(line)
+                    found_subject = True
+                elif line.startswith(("From:", "Date:")):
+                    msg_lines.append(line)
+                elif line.startswith((" ", "\t")) and found_subject:
+                    # Subject continuation
+                    msg_lines.append(line)
+                elif line == "":
+                    if found_subject:
+                        in_headers = False
+                        in_body = True
+                        msg_lines.append("")
+            elif in_body:
+                # Stop at the diffstat separator or diff
+                if line.rstrip() == "---":
+                    break
+                if line.startswith("diff --git"):
+                    break
+                msg_lines.append(line)
+
+        if msg_lines:
+            messages.append("\n".join(msg_lines))
+
+    return "\n\n---\n\n".join(messages)
+
+
+def truncate_content(content: str, max_tokens: float) -> tuple[str, bool]:
+    """Truncate content to fit within token limit."""
+    max_chars = int(max_tokens * CHARS_PER_TOKEN)
+
+    if len(content) <= max_chars:
+        return content, False
+
+    # Try to truncate at a reasonable boundary
+    truncated = content[:max_chars]
+
+    # Find last complete diff hunk or patch boundary
+    last_diff = truncated.rfind("\ndiff --git")
+    last_patch = truncated.rfind("\nFrom ")
+
+    if last_diff > max_chars * 0.5:
+        truncated = truncated[:last_diff]
+    elif last_patch > max_chars * 0.5:
+        truncated = truncated[:last_patch]
+
+    truncated += "\n\n[... Content truncated due to size limits ...]\n"
+    return truncated, True
+
+
+def chunk_content(content: str, max_tokens: int) -> Iterator[tuple[str, int, int]]:
+    """Split content into chunks that fit within token limit.
+
+    Yields tuples of (chunk_content, chunk_number, total_chunks).
+    """
+    patches = split_mbox_patches(content)
+
+    if len(patches) == 1:
+        # Single large patch - split by diff sections
+        yield from chunk_single_patch(content, max_tokens)
+        return
+
+    # Multiple patches - group them to fit within limits
+    chunks = []
+    current_chunk = []
+    current_size = 0
+    max_chars = int(max_tokens * CHARS_PER_TOKEN * 0.9)  # 90% to leave margin
+
+    for patch in patches:
+        patch_size = len(patch)
+        if current_size + patch_size > max_chars and current_chunk:
+            chunks.append("\n".join(current_chunk))
+            current_chunk = []
+            current_size = 0
+
+        if patch_size > max_chars:
+            # Single patch too large, truncate it
+            if current_chunk:
+                chunks.append("\n".join(current_chunk))
+                current_chunk = []
+                current_size = 0
+            truncated, _ = truncate_content(patch, max_tokens * 0.9)
+            chunks.append(truncated)
+        else:
+            current_chunk.append(patch)
+            current_size += patch_size
+
+    if current_chunk:
+        chunks.append("\n".join(current_chunk))
+
+    total = len(chunks)
+    for i, chunk in enumerate(chunks, 1):
+        yield chunk, i, total
+
+
+def chunk_single_patch(content: str, max_tokens: int) -> Iterator[tuple[str, int, int]]:
+    """Split a single large patch by diff sections."""
+    max_chars = int(max_tokens * CHARS_PER_TOKEN * 0.9)
+
+    # Extract header (everything before first diff)
+    first_diff = content.find("\ndiff --git")
+    if first_diff == -1:
+        # No diff sections, just truncate
+        truncated, _ = truncate_content(content, max_tokens * 0.9)
+        yield truncated, 1, 1
+        return
+
+    header = content[: first_diff + 1]
+    diff_content = content[first_diff + 1 :]
+
+    # Split by diff sections
+    diffs = []
+    current_diff = []
+    for line in diff_content.split("\n"):
+        if line.startswith("diff --git") and current_diff:
+            diffs.append("\n".join(current_diff))
+            current_diff = []
+        current_diff.append(line)
+    if current_diff:
+        diffs.append("\n".join(current_diff))
+
+    # Group diffs into chunks
+    chunks = []
+    current_chunk_diffs = []
+    current_size = len(header)
+
+    for diff in diffs:
+        diff_size = len(diff)
+        if current_size + diff_size > max_chars and current_chunk_diffs:
+            chunks.append(header + "\n".join(current_chunk_diffs))
+            current_chunk_diffs = []
+            current_size = len(header)
+
+        if diff_size + len(header) > max_chars:
+            # Single diff too large
+            if current_chunk_diffs:
+                chunks.append(header + "\n".join(current_chunk_diffs))
+                current_chunk_diffs = []
+            truncated_diff = diff[: max_chars - len(header) - 100]
+            truncated_diff += "\n[... diff truncated ...]\n"
+            chunks.append(header + truncated_diff)
+            current_size = len(header)
+        else:
+            current_chunk_diffs.append(diff)
+            current_size += diff_size
+
+    if current_chunk_diffs:
+        chunks.append(header + "\n".join(current_chunk_diffs))
+
+    total = len(chunks)
+    for i, chunk in enumerate(chunks, 1):
+        yield chunk, i, total
+
+
+def get_summary_prompt() -> str:
+    """Get prompt modifications for summary mode."""
+    return """
+NOTE: This is a LARGE patch series. Provide a HIGH-LEVEL summary review only:
+- Focus on overall architecture and design concerns
+- Check commit message formatting across the series
+- Identify any obvious policy violations
+- Do NOT attempt detailed line-by-line code review
+- Summarize the scope and purpose of the changes
+"""
+
+
+def format_combined_reviews(
+    reviews: list[tuple[str, str]], output_format: str, patch_name: str
+) -> str:
+    """Combine multiple chunk/patch reviews into a single output."""
+    if output_format == "json":
+        combined = {
+            "patch_file": patch_name,
+            "sections": [
+                {"label": label, "review": review} for label, review in reviews
+            ],
+        }
+        return json.dumps(combined, indent=2)
+    elif output_format == "html":
+        sections = []
+        for label, review in reviews:
+            sections.append(f"<h2>{label}</h2>\n{review}")
+        return "\n<hr>\n".join(sections)
+    elif output_format == "markdown":
+        sections = []
+        for label, review in reviews:
+            sections.append(f"## {label}\n\n{review}")
+        return "\n\n---\n\n".join(sections)
+    else:  # text
+        sections = []
+        for label, review in reviews:
+            sections.append(f"=== {label} ===\n\n{review}")
+        separator = "\n\n" + "=" * 60 + "\n\n"
+        return separator.join(sections)
+
+
+def build_system_prompt(review_date: str, release: str | None) -> str:
+    """Build system prompt with date and release context."""
+    prompt = SYSTEM_PROMPT_BASE
+    prompt += f"\n\nCurrent date: {review_date}."
+
+    if release:
+        prompt += f"\nTarget DPDK release: {release}."
+        if is_lts_release(release):
+            prompt += LTS_RULES
+        else:
+            prompt += "\nThis is a main branch or standard release."
+            prompt += "\nNew features and experimental APIs are allowed."
+
+    return prompt
+
+
+def build_anthropic_request(
+    model: str,
+    max_tokens: int,
+    system_prompt: str,
+    agents_content: str,
+    patch_content: str,
+    patch_name: str,
+    output_format: str = "text",
+) -> dict[str, Any]:
+    """Build request payload for Anthropic API."""
+    format_instruction = FORMAT_INSTRUCTIONS.get(output_format, "")
+    user_prompt = USER_PROMPT.format(
+        patch_name=patch_name, format_instruction=format_instruction
+    )
+    return {
+        "model": model,
+        "max_tokens": max_tokens,
+        "system": [
+            {"type": "text", "text": system_prompt},
+            {
+                "type": "text",
+                "text": agents_content,
+                "cache_control": {"type": "ephemeral"},
+            },
+        ],
+        "messages": [
+            {
+                "role": "user",
+                "content": user_prompt + patch_content,
+            }
+        ],
+    }
+
+
+def build_openai_request(
+    model: str,
+    max_tokens: int,
+    system_prompt: str,
+    agents_content: str,
+    patch_content: str,
+    patch_name: str,
+    output_format: str = "text",
+) -> dict[str, Any]:
+    """Build request payload for OpenAI-compatible APIs."""
+    format_instruction = FORMAT_INSTRUCTIONS.get(output_format, "")
+    user_prompt = USER_PROMPT.format(
+        patch_name=patch_name, format_instruction=format_instruction
+    )
+    return {
+        "model": model,
+        "max_tokens": max_tokens,
+        "messages": [
+            {"role": "system", "content": system_prompt},
+            {"role": "system", "content": agents_content},
+            {
+                "role": "user",
+                "content": user_prompt + patch_content,
+            },
+        ],
+    }
+
+
+def build_google_request(
+    max_tokens: int,
+    system_prompt: str,
+    agents_content: str,
+    patch_content: str,
+    patch_name: str,
+    output_format: str = "text",
+) -> dict[str, Any]:
+    """Build request payload for Google Gemini API."""
+    format_instruction = FORMAT_INSTRUCTIONS.get(output_format, "")
+    user_prompt = USER_PROMPT.format(
+        patch_name=patch_name, format_instruction=format_instruction
+    )
+    return {
+        "systemInstruction": {
+            "parts": [
+                {"text": system_prompt},
+                {"text": agents_content},
+            ]
+        },
+        "contents": [
+            {
+                "role": "user",
+                "parts": [{"text": user_prompt + patch_content}],
+            },
+        ],
+        "generationConfig": {"maxOutputTokens": max_tokens},
+    }
+
+
+def call_api(
+    provider: str,
+    api_key: str,
+    model: str,
+    max_tokens: int,
+    system_prompt: str,
+    agents_content: str,
+    patch_content: str,
+    patch_name: str,
+    output_format: str = "text",
+    verbose: bool = False,
+    timeout: int = 300,
+) -> tuple[str, TokenUsage]:
+    """Build the per-provider request body and dispatch via _common."""
+    if provider == "anthropic":
+        request_data = build_anthropic_request(
+            model,
+            max_tokens,
+            system_prompt,
+            agents_content,
+            patch_content,
+            patch_name,
+            output_format,
+        )
+    elif provider == "google":
+        request_data = build_google_request(
+            max_tokens,
+            system_prompt,
+            agents_content,
+            patch_content,
+            patch_name,
+            output_format,
+        )
+    else:  # openai, xai
+        request_data = build_openai_request(
+            model,
+            max_tokens,
+            system_prompt,
+            agents_content,
+            patch_content,
+            patch_name,
+            output_format,
+        )
+    return send_request(
+        provider,
+        api_key,
+        model,
+        request_data,
+        timeout=timeout,
+        verbose=verbose,
+    )
+
+
+def get_last_message_id(patch_content: str) -> str | None:
+    """Extract Message-ID from the last patch in an mbox."""
+    msg_ids = re.findall(
+        r"^Message-I[Dd]:\s*(.+)$", patch_content, re.MULTILINE | re.IGNORECASE
+    )
+    if msg_ids:
+        msg_id = msg_ids[-1].strip()
+        # Normalize: remove < > and add them back
+        msg_id = msg_id.strip("<>")
+        return f"<{msg_id}>"
+    return None
+
+
+def get_last_subject(patch_content: str) -> str | None:
+    """Extract subject from the last patch in an mbox."""
+    # Find all Subject lines with potential continuations
+    subjects = []
+    lines = patch_content.split("\n")
+    i = 0
+    while i < len(lines):
+        if lines[i].lower().startswith("subject:"):
+            subject = lines[i][8:].strip()
+            i += 1
+            # Handle continuation lines (RFC 2822 folding)
+            while i < len(lines) and lines[i].startswith((" ", "\t")):
+                subject += " " + lines[i].strip()
+                i += 1
+            subjects.append(subject)
+        else:
+            i += 1
+    return subjects[-1] if subjects else None
+
+
+def send_email(
+    to_addrs: list[str],
+    cc_addrs: list[str],
+    from_addr: str,
+    subject: str,
+    in_reply_to: str | None,
+    body: str,
+    dry_run: bool = False,
+) -> bool:
+    """Send review email using git send-email, sendmail, or msmtp.
+
+    TODO: This duplicates send_email in review-doc.py, which uses direct
+    smtplib with git sendemail.* config instead of shelling out. Both
+    approaches work; pick one and move it to _common.py.
+    """
+    msg = EmailMessage()
+    msg["From"] = from_addr
+    msg["To"] = ", ".join(to_addrs)
+    if cc_addrs:
+        msg["Cc"] = ", ".join(cc_addrs)
+    msg["Subject"] = subject
+    if in_reply_to:
+        msg["In-Reply-To"] = in_reply_to
+        msg["References"] = in_reply_to
+    msg.set_content(body)
+
+    email_text = msg.as_string()
+
+    if dry_run:
+        print("=== Email Preview (dry-run) ===", file=sys.stderr)
+        print(email_text, file=sys.stderr)
+        print("=== End Preview ===", file=sys.stderr)
+        return True
+
+    # Write to temp file for git send-email
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".eml", delete=False) as f:
+        f.write(email_text)
+        temp_file = f.name
+
+    try:
+        # Try git send-email first
+        if get_git_config("sendemail.smtpserver"):
+            # Build command with all arguments
+            flat_cmd = ["git", "send-email", "--confirm=never", "--quiet"]
+            for addr in to_addrs:
+                flat_cmd.extend(["--to", addr])
+            for addr in cc_addrs:
+                flat_cmd.extend(["--cc", addr])
+            if from_addr:
+                flat_cmd.extend(["--from", from_addr])
+            if in_reply_to:
+                flat_cmd.extend(["--in-reply-to", in_reply_to])
+            flat_cmd.append(temp_file)
+
+            try:
+                subprocess.run(flat_cmd, check=True, capture_output=True)
+                print("Email sent via git send-email", file=sys.stderr)
+                return True
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                pass
+
+        # Try sendmail
+        try:
+            subprocess.run(
+                ["sendmail", "-t"],
+                input=email_text,
+                text=True,
+                capture_output=True,
+                check=True,
+            )
+            print("Email sent via sendmail", file=sys.stderr)
+            return True
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+
+        # Try msmtp
+        try:
+            subprocess.run(
+                ["msmtp", "-t"],
+                input=email_text,
+                text=True,
+                capture_output=True,
+                check=True,
+            )
+            print("Email sent via msmtp", file=sys.stderr)
+            return True
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+
+        error("Could not send email. Configure git send-email, sendmail, or msmtp.")
+
+    finally:
+        os.unlink(temp_file)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Analyze DPDK patches using AI providers",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    %(prog)s patch.patch                    # Review with default settings
+    %(prog)s -p openai my-patch.patch       # Use OpenAI ChatGPT
+    %(prog)s -f markdown patch.patch        # Output as Markdown
+    %(prog)s -f json -o review.json patch.patch  # Save JSON to file
+    %(prog)s -f html -o review.html patch.patch  # Save HTML to file
+    %(prog)s -r 24.11 patch.patch           # Review for specific release
+    %(prog)s -r 24.11-lts patch.patch       # Review for LTS branch
+    %(prog)s --send-email --to [email protected] series.mbox
+    %(prog)s --send-email --to [email protected] --dry-run series.mbox
+
+Large File Handling:
+    %(prog)s --split-patches series.mbox    # Review each patch separately
+    %(prog)s --split-patches --patch-range 1-5 series.mbox  # Review patches 1-5
+    %(prog)s --large-file=truncate patch.mbox   # Truncate to fit limit
+    %(prog)s --large-file=commits-only series.mbox  # Review commit messages only
+    %(prog)s --large-file=summary series.mbox   # High-level summary only
+    %(prog)s --large-file=chunk series.mbox     # Split and review in chunks
+
+Large File Modes:
+    error       - Fail with error (default)
+    truncate    - Truncate content to fit token limit
+    chunk       - Split into chunks and review each
+    commits-only - Extract and review only commit messages
+    summary     - Request high-level summary review
+
+LTS Releases:
+    Use -r/--release with LTS version (e.g., 24.11-lts, 23.11) to enable
+    stricter review rules: bug fixes only, no new features or APIs.
+    Any DPDK release with minor version .11 is an LTS release.
+
+Token Usage:
+    Use --show-tokens (or -v/--verbose) to print a token usage summary
+    on stderr after the run. Off by default.
+
+Exit Codes:
+    0 - Clean review (no errors or warnings)
+    1 - Operational failure (missing API key, file not found, etc.)
+    2 - Review found warnings (no errors)
+    3 - Review found errors
+        """,
+    )
+
+    parser.add_argument("patch_file", nargs="?", help="Patch file to analyze")
+    parser.add_argument(
+        "-p",
+        "--provider",
+        choices=PROVIDERS.keys(),
+        default="anthropic",
+        help="AI provider (default: anthropic)",
+    )
+    parser.add_argument(
+        "-a",
+        "--agents",
+        default="AGENTS.md",
+        help="Path to AGENTS.md file (default: AGENTS.md)",
+    )
+    parser.add_argument(
+        "-m",
+        "--model",
+        help="Model to use (default: provider-specific)",
+    )
+    parser.add_argument(
+        "-t",
+        "--tokens",
+        type=int,
+        default=4096,
+        help="Max tokens for response (default: 4096)",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Show API request details",
+    )
+    add_token_args(parser)
+    parser.add_argument(
+        "-f",
+        "--format",
+        choices=OUTPUT_FORMATS,
+        default="text",
+        dest="output_format",
+        help="Output format: text, markdown, html, json (default: text)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        metavar="FILE",
+        help="Write output to file instead of stdout",
+    )
+    parser.add_argument(
+        "-l",
+        "--list-providers",
+        action="store_true",
+        help="List available providers and exit",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=300,
+        metavar="SECONDS",
+        help="API request timeout in seconds (default: 300)",
+    )
+
+    # Date and release options
+    parser.add_argument(
+        "-D",
+        "--date",
+        metavar="YYYY-MM-DD",
+        help="Review date context (default: today)",
+    )
+    parser.add_argument(
+        "-r",
+        "--release",
+        metavar="VERSION",
+        help="Target DPDK release (e.g., 24.11, 23.11-lts)",
+    )
+
+    # Large file handling options
+    large_group = parser.add_argument_group("Large File Handling")
+    large_group.add_argument(
+        "--large-file",
+        choices=LARGE_FILE_MODES,
+        default="error",
+        metavar="MODE",
+        help="How to handle large files: error (default), truncate, "
+        "chunk, commits-only, summary",
+    )
+    large_group.add_argument(
+        "--max-tokens",
+        type=int,
+        metavar="N",
+        help="Max input tokens (default: provider-specific)",
+    )
+    large_group.add_argument(
+        "--split-patches",
+        action="store_true",
+        help="Split mbox into individual patches and review each separately",
+    )
+    large_group.add_argument(
+        "--patch-range",
+        metavar="N-M",
+        help="Review only patches N through M (1-indexed, use with --split-patches)",
+    )
+
+    # Email options
+    email_group = parser.add_argument_group("Email Options")
+    email_group.add_argument(
+        "--send-email",
+        action="store_true",
+        help="Send review via email",
+    )
+    email_group.add_argument(
+        "--to",
+        action="append",
+        dest="to_addrs",
+        default=[],
+        metavar="ADDRESS",
+        help="Email recipient (can be specified multiple times)",
+    )
+    email_group.add_argument(
+        "--cc",
+        action="append",
+        dest="cc_addrs",
+        default=[],
+        metavar="ADDRESS",
+        help="CC recipient (can be specified multiple times)",
+    )
+    email_group.add_argument(
+        "--from",
+        dest="from_addr",
+        metavar="ADDRESS",
+        help="From address (default: from git config)",
+    )
+    email_group.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show email without sending",
+    )
+
+    args = parser.parse_args()
+
+    if args.list_providers:
+        list_providers()
+
+    # Check patch file is provided
+    if not args.patch_file:
+        parser.error("patch_file is required")
+
+    # Get provider config
+    config = PROVIDERS[args.provider]
+    model = args.model or config["default_model"]
+
+    # Get API key
+    api_key = os.environ.get(config["env_var"])
+    if not api_key:
+        error(f"{config['env_var']} environment variable not set")
+
+    # Validate files
+    agents_path = Path(args.agents)
+    if not agents_path.exists():
+        error(f"AGENTS.md not found: {args.agents}")
+
+    patch_path = Path(args.patch_file)
+    if not patch_path.exists():
+        error(f"Patch file not found: {args.patch_file}")
+
+    # Validate email options
+    if args.send_email and not args.to_addrs:
+        error("--send-email requires at least one --to address")
+
+    # Get from address for email
+    from_addr = args.from_addr
+    if args.send_email and not from_addr:
+        git_name = get_git_config("user.name")
+        git_email = get_git_config("user.email")
+        if git_email:
+            from_addr = f"{git_name} <{git_email}>" if git_name else git_email
+        else:
+            error("No --from specified and git user.email not configured")
+
+    # Determine review date
+    review_date = args.date or date.today().isoformat()
+
+    # Build system prompt with date and release context
+    system_prompt = build_system_prompt(review_date, args.release)
+
+    # Read files
+    # Files may have non-UTF-8 bytes (binary patches, unusual filenames); replace
+    # rather than crashing so the review can still run.
+    agents_content = agents_path.read_text(encoding="utf-8", errors="replace")
+    patch_content = patch_path.read_text(encoding="utf-8", errors="replace")
+    patch_name = patch_path.name
+
+    # Determine max tokens for this provider
+    max_input_tokens = args.max_tokens or PROVIDER_INPUT_LIMITS.get(
+        args.provider, 100000
+    )
+
+    # Estimate token count
+    estimated_tokens = estimate_tokens(patch_content + agents_content)
+
+    # Accumulate token usage across all API calls
+    total_usage = TokenUsage()
+
+    # Parse patch range if specified
+    patch_start, patch_end = None, None
+    if args.patch_range:
+        try:
+            if "-" in args.patch_range:
+                start, end = args.patch_range.split("-", 1)
+                patch_start = int(start)
+                patch_end = int(end)
+            else:
+                patch_start = patch_end = int(args.patch_range)
+        except ValueError:
+            error(f"Invalid --patch-range format: {args.patch_range}")
+        if not args.split_patches:
+            print(
+                "Warning: --patch-range has no effect without --split-patches",
+                file=sys.stderr,
+            )
+
+    # Handle --split-patches mode
+    review_text = ""
+    if args.split_patches:
+        patches = split_mbox_patches(patch_content)
+        total_patches = len(patches)
+
+        if total_patches == 1:
+            print(
+                "Note: Only 1 patch found in mbox, --split-patches has no effect",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                f"Found {total_patches} patches in mbox",
+                file=sys.stderr,
+            )
+
+            # Apply patch range filter
+            if patch_start is not None:
+                if patch_start < 1 or patch_start > total_patches:
+                    error(
+                        f"Patch range start {patch_start} out of range (1-{total_patches})"
+                    )
+                if patch_end < patch_start or patch_end > total_patches:
+                    error(
+                        f"Patch range end {patch_end} out of range ({patch_start}-{total_patches})"
+                    )
+                patches = patches[patch_start - 1 : patch_end]
+                print(
+                    f"Reviewing patches {patch_start}-{patch_end} ({len(patches)} patches)",
+                    file=sys.stderr,
+                )
+
+            # Review each patch separately
+            all_reviews = []
+            for i, patch in enumerate(patches, patch_start or 1):
+                patch_label = f"Patch {i}/{total_patches}"
+                print(f"\nReviewing {patch_label}...", file=sys.stderr)
+
+                review_text, call_usage = call_api(
+                    args.provider,
+                    api_key,
+                    model,
+                    args.tokens,
+                    system_prompt,
+                    agents_content,
+                    patch,
+                    f"{patch_name} ({patch_label})",
+                    args.output_format,
+                    args.verbose,
+                    args.timeout,
+                )
+                total_usage.add(call_usage)
+                all_reviews.append((patch_label, review_text))
+
+            # Combine reviews
+            review_text = format_combined_reviews(
+                all_reviews, args.output_format, patch_name
+            )
+
+            # Skip the normal API call
+            estimated_tokens = 0  # Bypass size check since we've already processed
+
+    # Check if content is too large
+    is_large = estimated_tokens > max_input_tokens
+
+    if is_large:
+        print(
+            f"Warning: Estimated {estimated_tokens:,} tokens exceeds limit of "
+            f"{max_input_tokens:,}",
+            file=sys.stderr,
+        )
+
+        if args.large_file == "error":
+            error(
+                f"Patch file too large ({estimated_tokens:,} tokens). "
+                f"Use --large-file=truncate|chunk|commits-only|summary to handle, "
+                f"or --split-patches to review patches individually."
+            )
+        elif args.large_file == "truncate":
+            print("Truncating content to fit token limit...", file=sys.stderr)
+            patch_content, was_truncated = truncate_content(
+                patch_content, max_input_tokens
+            )
+            if was_truncated:
+                print("Content was truncated.", file=sys.stderr)
+        elif args.large_file == "commits-only":
+            print("Extracting commit messages only...", file=sys.stderr)
+            patch_content = extract_commit_messages(patch_content)
+            new_estimate = estimate_tokens(patch_content + agents_content)
+            print(
+                f"Reduced to ~{new_estimate:,} tokens (commit messages only)",
+                file=sys.stderr,
+            )
+            if new_estimate > max_input_tokens:
+                patch_content, _ = truncate_content(patch_content, max_input_tokens)
+        elif args.large_file == "summary":
+            print("Using summary mode for large patch...", file=sys.stderr)
+            system_prompt += get_summary_prompt()
+            patch_content, _ = truncate_content(patch_content, max_input_tokens)
+        elif args.large_file == "chunk":
+            print("Processing in chunks...", file=sys.stderr)
+            all_reviews = []
+            for chunk, chunk_num, total_chunks in chunk_content(
+                patch_content, max_input_tokens
+            ):
+                chunk_label = f"Chunk {chunk_num}/{total_chunks}"
+                print(f"Reviewing {chunk_label}...", file=sys.stderr)
+
+                review_text, call_usage = call_api(
+                    args.provider,
+                    api_key,
+                    model,
+                    args.tokens,
+                    system_prompt,
+                    agents_content,
+                    chunk,
+                    f"{patch_name} ({chunk_label})",
+                    args.output_format,
+                    args.verbose,
+                    args.timeout,
+                )
+                total_usage.add(call_usage)
+                all_reviews.append((chunk_label, review_text))
+
+            # Combine chunk reviews
+            review_text = format_combined_reviews(
+                all_reviews, args.output_format, patch_name
+            )
+
+            # Skip the normal single API call below
+            estimated_tokens = 0
+
+    if args.verbose:
+        print("=== Request ===", file=sys.stderr)
+        print(f"Provider: {args.provider}", file=sys.stderr)
+        print(f"Model: {model}", file=sys.stderr)
+        print(f"Review date: {review_date}", file=sys.stderr)
+        if args.release:
+            lts_status = " (LTS)" if is_lts_release(args.release) else ""
+            print(f"Target release: {args.release}{lts_status}", file=sys.stderr)
+        print(f"Output format: {args.output_format}", file=sys.stderr)
+        print(f"AGENTS file: {args.agents}", file=sys.stderr)
+        print(f"Patch file: {args.patch_file}", file=sys.stderr)
+        print(f"Estimated tokens: {estimated_tokens:,}", file=sys.stderr)
+        print(f"Max input tokens: {max_input_tokens:,}", file=sys.stderr)
+        if args.large_file != "error":
+            print(f"Large file mode: {args.large_file}", file=sys.stderr)
+        if args.split_patches:
+            print("Split patches: yes", file=sys.stderr)
+        if args.output:
+            print(f"Output file: {args.output}", file=sys.stderr)
+        if args.send_email:
+            print("Send email: yes", file=sys.stderr)
+            print(f"To: {', '.join(args.to_addrs)}", file=sys.stderr)
+            if args.cc_addrs:
+                print(f"Cc: {', '.join(args.cc_addrs)}", file=sys.stderr)
+            print(f"From: {from_addr}", file=sys.stderr)
+        print("===============", file=sys.stderr)
+
+    # Call API (unless already processed via chunks/split)
+    if estimated_tokens > 0:  # Not already processed
+        review_text, call_usage = call_api(
+            args.provider,
+            api_key,
+            model,
+            args.tokens,
+            system_prompt,
+            agents_content,
+            patch_content,
+            patch_name,
+            args.output_format,
+            args.verbose,
+            args.timeout,
+        )
+        total_usage.add(call_usage)
+
+    if not review_text:
+        error(f"No response received from {args.provider}")
+
+    # Format output based on requested format
+    provider_name = config["name"]
+
+    if args.output_format == "json":
+        # For JSON, try to parse and add metadata
+        try:
+            review_data = json.loads(review_text)
+        except json.JSONDecodeError:
+            # If AI didn't return valid JSON, wrap the text
+            review_data = {"raw_review": review_text}
+
+        usage_data = {
+            "api_calls": total_usage.api_calls,
+            "input_tokens": total_usage.input_tokens,
+            "output_tokens": total_usage.output_tokens,
+            "total_tokens": total_usage.input_tokens + total_usage.output_tokens,
+        }
+        if total_usage.cache_creation_tokens:
+            usage_data["cache_creation_tokens"] = total_usage.cache_creation_tokens
+        if total_usage.cache_read_tokens:
+            usage_data["cache_read_tokens"] = total_usage.cache_read_tokens
+
+        output_data = {
+            "metadata": {
+                "patch_file": patch_name,
+                "provider": args.provider,
+                "provider_name": provider_name,
+                "model": model,
+                "review_date": review_date,
+                "target_release": args.release,
+                "is_lts": is_lts_release(args.release) if args.release else False,
+                "token_usage": usage_data,
+            },
+            "review": review_data,
+        }
+        output_text = json.dumps(output_data, indent=2)
+    elif args.output_format == "html":
+        # Wrap HTML content with header
+        release_info = ""
+        if args.release:
+            lts_badge = " (LTS)" if is_lts_release(args.release) else ""
+            release_info = f"<br>Target release: {args.release}{lts_badge}"
+        output_text = f"""<!-- AI-generated review of {patch_name} -->
+<!-- Reviewed using {provider_name} ({model}) on {review_date} -->
+<div class="patch-review">
+<h1>Patch Review: {patch_name}</h1>
+<p class="review-meta">Reviewed by {provider_name} ({model}) on {review_date}{release_info}</p>
+{review_text}
+</div>
+"""
+    elif args.output_format == "markdown":
+        release_info = ""
+        if args.release:
+            lts_badge = " (LTS)" if is_lts_release(args.release) else ""
+            release_info = f"\n*Target release: {args.release}{lts_badge}*\n"
+        output_text = f"""# Patch Review: {patch_name}
+
+*Reviewed by {provider_name} ({model}) on {review_date}*
+{release_info}
+{review_text}
+"""
+    else:  # text
+        release_info = ""
+        if args.release:
+            lts_badge = " (LTS)" if is_lts_release(args.release) else ""
+            release_info = f"Target release: {args.release}{lts_badge}\n"
+        output_text = f"=== Patch Review: {patch_name} (via {provider_name}) ===\n"
+        output_text += f"Review date: {review_date}\n"
+        output_text += release_info
+        output_text += "\n" + review_text
+
+    # Write output
+    if args.output:
+        Path(args.output).write_text(output_text)
+        print(f"Review written to: {args.output}", file=sys.stderr)
+    else:
+        print(output_text)
+
+    print_token_summary(
+        total_usage,
+        args.provider,
+        model,
+        args.show_tokens or args.verbose,
+    )
+
+    # Send email if requested
+    if args.send_email:
+        # Email always uses plain text - warn if different format requested
+        if args.output_format != "text":
+            print(
+                f"Note: Email will be sent as plain text regardless of "
+                f"--format={args.output_format}",
+                file=sys.stderr,
+            )
+
+        in_reply_to = get_last_message_id(patch_content)
+        orig_subject = get_last_subject(patch_content)
+
+        if orig_subject:
+            # Remove [PATCH n/m] prefix
+            review_subject = re.sub(r"^\[PATCH[^\]]*\]\s*", "", orig_subject)
+            review_subject = f"[REVIEW] {review_subject}"
+        else:
+            review_subject = f"[REVIEW] {patch_name}"
+
+        # Build email body - always use plain text version
+        release_info = ""
+        if args.release:
+            lts_badge = " (LTS)" if is_lts_release(args.release) else ""
+            release_info = f"Target release: {args.release}{lts_badge}\n"
+
+        email_body = f"""AI-generated review of {patch_name}
+Reviewed using {provider_name} ({model}) on {review_date}
+{release_info}
+This is an automated review. Please verify all suggestions.
+
+---
+
+{review_text}
+"""
+
+        if args.verbose:
+            print("", file=sys.stderr)
+            print("=== Email Details ===", file=sys.stderr)
+            print(f"Subject: {review_subject}", file=sys.stderr)
+            print(f"In-Reply-To: {in_reply_to}", file=sys.stderr)
+            print("=====================", file=sys.stderr)
+
+        send_email(
+            args.to_addrs,
+            args.cc_addrs,
+            from_addr,
+            review_subject,
+            in_reply_to,
+            email_body,
+            args.dry_run,
+        )
+
+        if not args.dry_run:
+            print("", file=sys.stderr)
+            print(f"Review sent to: {', '.join(args.to_addrs)}", file=sys.stderr)
+
+    # Exit with code based on review severity
+    sys.exit(classify_review(review_text, args.output_format))
+
+
+if __name__ == "__main__":
+    main()

new file mode 100755
index 0000000000..ba6d3a3eba
@@ -0,0 +1,306 @@
+#!/bin/bash
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2026 Stephen Hemminger
+
+# Compare DPDK patch reviews across multiple AI providers
+# Runs analyze-patch.py with each available provider
+
+set -o pipefail
+
+SCRIPT_DIR="$(dirname "$(readlink -f "$0")")"
+ANALYZE_SCRIPT="${SCRIPT_DIR}/analyze-patch.py"
+AGENTS_FILE="AGENTS.md"
+OUTPUT_DIR=""
+PROVIDERS=""
+FORMAT="text"
+VERBOSE=""
+EXTRA_ARGS=()
+
+usage() {
+    cat <<EOF
+Usage: $(basename "$0") [OPTIONS] <patch-file>
+
+Compare DPDK patch reviews across multiple AI providers.
+
+Options:
+    -a, --agents FILE      Path to AGENTS.md file (default: AGENTS.md)
+    -o, --output DIR       Save individual reviews to directory
+    -p, --providers LIST   Comma-separated list of providers to use
+                           (default: all providers with API keys set)
+    -f, --format FORMAT    Output format: text, markdown, html, json
+                           (default: text)
+    -t, --tokens N         Max tokens for response
+    -D, --date DATE        Review date context (YYYY-MM-DD)
+    -r, --release VERSION  Target DPDK release (e.g., 24.11, 23.11-lts)
+    --split-patches        Split mbox into individual patches
+    --patch-range N-M      Review only patches N through M
+    --large-file MODE      Handle large files: error, truncate, chunk,
+                           commits-only, summary
+    --max-tokens N         Max input tokens
+    -v, --verbose          Show verbose output from each provider
+    -h, --help             Show this help message
+
+Environment Variables:
+    Set API keys for providers you want to use:
+    ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, GOOGLE_API_KEY
+
+Examples:
+    $(basename "$0") my-patch.patch
+    $(basename "$0") -p anthropic,openai my-patch.patch
+    $(basename "$0") -o ./reviews -f markdown my-patch.patch
+    $(basename "$0") -r 24.11 --split-patches series.mbox
+
+Exit code from analyze-patch.py is interpreted as:
+    0    clean review
+    2    review found warnings (output preserved)
+    3    review found errors   (output preserved)
+    1/*  operational failure   (output removed, counted as failure)
+EOF
+    exit "${1:-0}"
+}
+
+error() {
+    echo "Error: $1" >&2
+    exit 1
+}
+
+# Check which providers have API keys configured
+get_available_providers() {
+    local available=""
+
+    [[ -n "$ANTHROPIC_API_KEY" ]] && available="${available}anthropic,"
+    [[ -n "$OPENAI_API_KEY" ]] && available="${available}openai,"
+    [[ -n "$XAI_API_KEY" ]] && available="${available}xai,"
+    [[ -n "$GOOGLE_API_KEY" ]] && available="${available}google,"
+
+    # Remove trailing comma
+    echo "${available%,}"
+}
+
+# Get file extension for format
+get_extension() {
+    case "$1" in
+        text)     echo "txt" ;;
+        markdown) echo "md" ;;
+        html)     echo "html" ;;
+        json)     echo "json" ;;
+        *)        echo "txt" ;;
+    esac
+}
+
+# Parse command line options
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -a|--agents)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            AGENTS_FILE="$2"
+            shift 2
+            ;;
+        -o|--output)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            OUTPUT_DIR="$2"
+            shift 2
+            ;;
+        -p|--providers)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            PROVIDERS="$2"
+            shift 2
+            ;;
+        -f|--format)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            FORMAT="$2"
+            shift 2
+            ;;
+        -t|--tokens)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            EXTRA_ARGS+=("-t" "$2")
+            shift 2
+            ;;
+        -D|--date)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            EXTRA_ARGS+=("-D" "$2")
+            shift 2
+            ;;
+        -r|--release)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            EXTRA_ARGS+=("-r" "$2")
+            shift 2
+            ;;
+        --split-patches)
+            EXTRA_ARGS+=("--split-patches")
+            shift
+            ;;
+        --patch-range)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            EXTRA_ARGS+=("--patch-range" "$2")
+            shift 2
+            ;;
+        --large-file)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            EXTRA_ARGS+=("--large-file" "$2")
+            shift 2
+            ;;
+        --large-file=*)
+            EXTRA_ARGS+=("$1")
+            shift
+            ;;
+        --max-tokens)
+            [[ -z "${2:-}" || "$2" == -* ]] && error "$1 requires an argument"
+            EXTRA_ARGS+=("--max-tokens" "$2")
+            shift 2
+            ;;
+        -v|--verbose)
+            VERBOSE="-v"
+            shift
+            ;;
+        -h|--help)
+            usage 0
+            ;;
+        -*)
+            error "Unknown option: $1"
+            ;;
+        *)
+            break
+            ;;
+    esac
+done
+
+# Check for required arguments
+if [[ $# -lt 1 ]]; then
+    echo "Error: No patch file specified" >&2
+    usage 1
+fi
+
+PATCH_FILE="$1"
+
+if [[ ! -f "$PATCH_FILE" ]]; then
+    error "Patch file not found: $PATCH_FILE"
+fi
+
+if [[ ! -f "$ANALYZE_SCRIPT" ]]; then
+    error "analyze-patch.py not found: $ANALYZE_SCRIPT"
+fi
+
+if [[ ! -f "$AGENTS_FILE" ]]; then
+    error "AGENTS.md not found: $AGENTS_FILE"
+fi
+
+# Validate format
+case "$FORMAT" in
+    text|markdown|html|json) ;;
+    *) error "Invalid format: $FORMAT (must be text, markdown, html, or json)" ;;
+esac
+
+# Get providers to use
+if [[ -z "$PROVIDERS" ]]; then
+    PROVIDERS=$(get_available_providers)
+fi
+
+if [[ -z "$PROVIDERS" ]]; then
+    error "No API keys configured. Set at least one of: "\
+"ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, GOOGLE_API_KEY"
+fi
+
+# Create output directory if specified
+if [[ -n "$OUTPUT_DIR" ]]; then
+    mkdir -p "$OUTPUT_DIR"
+fi
+
+PATCH_BASENAME=$(basename "$PATCH_FILE")
+PATCH_STEM="${PATCH_BASENAME%.*}"
+EXT=$(get_extension "$FORMAT")
+
+echo "Reviewing patch: $PATCH_BASENAME"
+echo "Providers: $PROVIDERS"
+echo "Format: $FORMAT"
+echo "========================================"
+echo ""
+
+# Run review for each provider; continue on failure of any one provider.
+#
+# analyze-patch.py exit codes:
+#   0 - clean review (no issues)
+#   1 - operational failure (missing key, file not found, network error, etc.)
+#   2 - review found warnings
+#   3 - review found errors
+# Exit 2 and 3 mean the review SUCCEEDED and produced output the user wants
+# to read. Only 1 (and unexpected codes) indicate a failed run.
+IFS=',' read -ra PROVIDER_LIST <<< "$PROVIDERS"
+failures=0
+warnings_count=0
+errors_count=0
+for provider in "${PROVIDER_LIST[@]}"; do
+    echo ">>> Running review with: $provider"
+    echo ""
+
+    OUTPUT_FILE=""
+    if [[ -n "$OUTPUT_DIR" ]]; then
+        OUTPUT_FILE="${OUTPUT_DIR}/${PATCH_STEM}-${provider}.${EXT}"
+        python3 "$ANALYZE_SCRIPT" \
+            -p "$provider" \
+            -a "$AGENTS_FILE" \
+            -f "$FORMAT" \
+            ${VERBOSE:+"$VERBOSE"} \
+            "${EXTRA_ARGS[@]}" \
+            "$PATCH_FILE" | tee "$OUTPUT_FILE"
+        rc=${PIPESTATUS[0]}
+    else
+        python3 "$ANALYZE_SCRIPT" \
+            -p "$provider" \
+            -a "$AGENTS_FILE" \
+            -f "$FORMAT" \
+            ${VERBOSE:+"$VERBOSE"} \
+            "${EXTRA_ARGS[@]}" \
+            "$PATCH_FILE"
+        rc=$?
+    fi
+
+    case "$rc" in
+        0)
+            if [[ -n "$OUTPUT_FILE" ]]; then
+                echo ""
+                echo "Saved to: $OUTPUT_FILE"
+            fi
+            ;;
+        2)
+            ((warnings_count++)) || true
+            echo "($provider: review reported warnings)" >&2
+            if [[ -n "$OUTPUT_FILE" ]]; then
+                echo ""
+                echo "Saved to: $OUTPUT_FILE"
+            fi
+            ;;
+        3)
+            ((errors_count++)) || true
+            echo "($provider: review reported errors)" >&2
+            if [[ -n "$OUTPUT_FILE" ]]; then
+                echo ""
+                echo "Saved to: $OUTPUT_FILE"
+            fi
+            ;;
+        *)
+            echo "FAILED: $provider review failed (exit $rc)" >&2
+            [[ -n "$OUTPUT_FILE" ]] && rm -f "$OUTPUT_FILE"
+            ((failures++)) || true
+            ;;
+    esac
+
+    echo ""
+    echo "========================================"
+    echo ""
+done
+
+total=${#PROVIDER_LIST[@]}
+clean_count=$((total - warnings_count - errors_count - failures))
+
+echo "Review comparison complete."
+echo "Summary across $total provider(s): clean=$clean_count" \
+     "warnings=$warnings_count errors=$errors_count failed=$failures"
+
+if [[ -n "$OUTPUT_DIR" ]]; then
+    echo "Reviews saved to: $OUTPUT_DIR"
+fi
+
+if [[ $failures -gt 0 ]]; then
+    exit 1
+fi

new file mode 100755
index 0000000000..22b5614415
@@ -0,0 +1,1013 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2026 Stephen Hemminger
+
+"""
+Review DPDK documentation files using AI providers.
+
+Produces a diff file and commit message compliant with DPDK standards.
+Accepts multiple documentation files and generates output for each.
+Supported providers: Anthropic Claude, OpenAI ChatGPT, xAI Grok, Google Gemini
+"""
+
+import argparse
+import getpass
+import json
+import os
+import re
+import smtplib
+import ssl
+import sys
+from email.message import EmailMessage
+from pathlib import Path
+from typing import Any
+
+from _common import (
+    PROVIDERS,
+    TokenUsage,
+    add_token_args,
+    error,
+    get_git_config,
+    list_providers,
+    print_token_summary,
+    send_request,
+)
+
+# Map output format to file extension
+FORMAT_EXTENSIONS = {
+    "text": ".txt",
+    "markdown": ".md",
+    "html": ".html",
+    "json": ".json",
+}
+
+# Additional markers for extracting diff/msg (used with --diff flag)
+DIFF_MARKERS_INSTRUCTION = """
+
+ADDITIONALLY, at the end of your response, include these exact markers for automated extraction:
+---COMMIT_MESSAGE_START---
+(same commit message as above)
+---COMMIT_MESSAGE_END---
+
+---UNIFIED_DIFF_START---
+(same unified diff as above)
+---UNIFIED_DIFF_END---
+"""
+
+# Commit prefix mappings based on file path
+COMMIT_PREFIX_MAP = [
+    ("doc/guides/prog_guide/", "doc/guides/prog_guide:"),
+    ("doc/guides/sample_app_ug/", "doc/guides/sample_app:"),
+    ("doc/guides/nics/", "doc/guides/nics:"),
+    ("doc/guides/cryptodevs/", "doc/guides/cryptodevs:"),
+    ("doc/guides/compressdevs/", "doc/guides/compressdevs:"),
+    ("doc/guides/eventdevs/", "doc/guides/eventdevs:"),
+    ("doc/guides/rawdevs/", "doc/guides/rawdevs:"),
+    ("doc/guides/bbdevs/", "doc/guides/bbdevs:"),
+    ("doc/guides/gpus/", "doc/guides/gpus:"),
+    ("doc/guides/dmadevs/", "doc/guides/dmadevs:"),
+    ("doc/guides/regexdevs/", "doc/guides/regexdevs:"),
+    ("doc/guides/mldevs/", "doc/guides/mldevs:"),
+    ("doc/guides/rel_notes/", "doc/guides/rel_notes:"),
+    ("doc/guides/linux_gsg/", "doc/guides/linux_gsg:"),
+    ("doc/guides/freebsd_gsg/", "doc/guides/freebsd_gsg:"),
+    ("doc/guides/windows_gsg/", "doc/guides/windows_gsg:"),
+    ("doc/guides/tools/", "doc/guides/tools:"),
+    ("doc/guides/testpmd_app_ug/", "doc/guides/testpmd:"),
+    ("doc/guides/howto/", "doc/guides/howto:"),
+    ("doc/guides/contributing/", "doc/guides/contributing:"),
+    ("doc/guides/platform/", "doc/guides/platform:"),
+    ("doc/guides/", "doc:"),
+    ("doc/api/", "doc/api:"),
+    ("doc/", "doc:"),
+]
+
+SYSTEM_PROMPT = """\
+You are an expert technical documentation reviewer for DPDK.
+Your task is to review documentation files and suggest improvements for:
+- Spelling errors
+- Grammar issues
+- Technical correctness
+- Clarity and readability
+- Consistency with DPDK terminology
+
+IMPORTANT COMMIT MESSAGE RULES (from check-git-log.sh):
+- Subject line MUST be <=60 characters
+- Format: "prefix: lowercase description"
+- First word after colon must be lowercase (except acronyms like Rx, Tx, VF, MAC, API)
+- Use imperative mood (e.g., "fix typo" not "fixed typo" or "fixes typo")
+- NO trailing period on subject line
+- NO punctuation marks: , ; ! ? & |
+- NO underscores in subject after colon
+- Body lines wrapped at 75 characters
+- Body must NOT start with "It"
+- Do NOT include Signed-off-by (user adds via git commit --sign)
+- Only use "Fixes:" tag for actual errors in documentation, not style improvements
+
+Case-sensitive terms (must use exact case):
+- Rx, Tx (not RX, TX, rx, tx)
+- VF, PF (not vf, pf)
+- MAC, VLAN, RSS, API
+- Linux, Windows, FreeBSD
+
+For style/clarity improvements, do NOT use Fixes tag.
+For actual errors (wrong information, broken examples), include Fixes tag \
+if you can identify the commit."""
+
+FORMAT_INSTRUCTIONS = {
+    "text": """
+OUTPUT FORMAT:
+You must output exactly two sections:
+
+1. COMMIT_MESSAGE section containing the complete commit message
+2. UNIFIED_DIFF section containing the unified diff
+
+Use these exact markers:
+---COMMIT_MESSAGE_START---
+(commit message here)
+---COMMIT_MESSAGE_END---
+
+---UNIFIED_DIFF_START---
+(unified diff here)
+---UNIFIED_DIFF_END---
+
+The diff should be in unified format that can be applied with "git apply".
+If no changes are needed, output empty sections with a note.""",
+    "markdown": """
+OUTPUT FORMAT:
+Provide your review in Markdown format with:
+
+## Summary
+Brief description of changes
+
+## Commit Message
+```
+(complete commit message here, ready to use)
+```
+
+## Changes
+For each change:
+### Issue N: Brief title
+- **Location**: file path and line
+- **Problem**: description
+- **Fix**: suggested correction
+
+## Unified Diff
+```diff
+(unified diff here)
+```""",
+    "html": """
+OUTPUT FORMAT:
+Provide your review in HTML format with:
+- <h2> for sections (Summary, Commit Message, Changes, Diff)
+- <pre><code> for commit message and diff
+- <ul>/<li> for individual issues
+- Do NOT include <html>, <head>, or <body> tags - just the content
+
+Include sections for: Summary, Commit Message, Changes, Unified Diff""",
+    "json": """
+OUTPUT FORMAT:
+Provide your review as JSON with this structure:
+{
+  "summary": "Brief description of changes",
+  "commit_message": "Complete commit message ready to use",
+  "changes": [
+    {
+      "type": "spelling|grammar|technical|clarity|style",
+      "location": "line number or section",
+      "original": "original text",
+      "suggested": "corrected text",
+      "reason": "why this change"
+    }
+  ],
+  "diff": "unified diff as a string",
+  "stats": {
+    "total_issues": 0,
+    "spelling": 0,
+    "grammar": 0,
+    "technical": 0,
+    "clarity": 0
+  }
+}
+Output ONLY valid JSON, no markdown code fences or other text.""",
+}
+
+USER_PROMPT = """\
+Review the following DPDK documentation file and provide improvements.
+
+File path: {doc_file}
+Commit message prefix to use: {commit_prefix}
+
+{format_instruction}
+
+---DOCUMENT CONTENT---
+"""
+
+
+def get_smtp_config() -> dict[str, Any]:
+    """Get SMTP configuration from git config sendemail settings."""
+    config = {
+        "server": get_git_config("sendemail.smtpserver"),
+        "port": get_git_config("sendemail.smtpserverport"),
+        "user": get_git_config("sendemail.smtpuser"),
+        "encryption": get_git_config("sendemail.smtpencryption"),
+        "password": get_git_config("sendemail.smtppass"),
+    }
+
+    # Set defaults
+    if not config["port"]:
+        if config["encryption"] == "ssl":
+            config["port"] = "465"
+        else:
+            config["port"] = "587"
+
+    # Convert port to int
+    try:
+        config["port"] = int(config["port"])
+    except (TypeError, ValueError):
+        error(
+            f"Invalid sendemail.smtpserverport: {config['port']!r} "
+            "(must be a number)"
+        )
+
+    return config
+
+
+def get_commit_prefix(filepath: str) -> str:
+    """Determine commit message prefix from file path."""
+    for prefix_path, prefix in COMMIT_PREFIX_MAP:
+        if filepath.startswith(prefix_path):
+            return prefix
+    return "doc:"
+
+
+def build_user_prompt(
+    doc_file: str,
+    commit_prefix: str,
+    output_format: str = "text",
+    include_diff_markers: bool = False,
+) -> str:
+    """Build the user prompt with format instructions."""
+    format_instruction = FORMAT_INSTRUCTIONS.get(output_format, "")
+    if include_diff_markers and output_format not in ("text", "json"):
+        format_instruction += DIFF_MARKERS_INSTRUCTION
+    return USER_PROMPT.format(
+        doc_file=doc_file,
+        commit_prefix=commit_prefix,
+        format_instruction=format_instruction,
+    )
+
+
+def build_anthropic_request(
+    model: str,
+    max_tokens: int,
+    agents_content: str,
+    doc_content: str,
+    doc_file: str,
+    commit_prefix: str,
+    output_format: str = "text",
+    include_diff_markers: bool = False,
+) -> dict[str, Any]:
+    """Build request payload for Anthropic API."""
+    user_prompt = build_user_prompt(
+        doc_file, commit_prefix, output_format, include_diff_markers
+    )
+    return {
+        "model": model,
+        "max_tokens": max_tokens,
+        "system": [
+            {"type": "text", "text": SYSTEM_PROMPT},
+            {
+                "type": "text",
+                "text": agents_content,
+                "cache_control": {"type": "ephemeral"},
+            },
+        ],
+        "messages": [
+            {
+                "role": "user",
+                "content": user_prompt + doc_content,
+            }
+        ],
+    }
+
+
+def build_openai_request(
+    model: str,
+    max_tokens: int,
+    agents_content: str,
+    doc_content: str,
+    doc_file: str,
+    commit_prefix: str,
+    output_format: str = "text",
+    include_diff_markers: bool = False,
+) -> dict[str, Any]:
+    """Build request payload for OpenAI-compatible APIs."""
+    user_prompt = build_user_prompt(
+        doc_file, commit_prefix, output_format, include_diff_markers
+    )
+    return {
+        "model": model,
+        "max_tokens": max_tokens,
+        "messages": [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "system", "content": agents_content},
+            {
+                "role": "user",
+                "content": user_prompt + doc_content,
+            },
+        ],
+    }
+
+
+def build_google_request(
+    max_tokens: int,
+    agents_content: str,
+    doc_content: str,
+    doc_file: str,
+    commit_prefix: str,
+    output_format: str = "text",
+    include_diff_markers: bool = False,
+) -> dict[str, Any]:
+    """Build request payload for Google Gemini API."""
+    user_prompt = build_user_prompt(
+        doc_file, commit_prefix, output_format, include_diff_markers
+    )
+    return {
+        "systemInstruction": {
+            "parts": [
+                {"text": SYSTEM_PROMPT},
+                {"text": agents_content},
+            ],
+        },
+        "contents": [
+            {
+                "role": "user",
+                "parts": [{"text": user_prompt + doc_content}],
+            },
+        ],
+        "generationConfig": {"maxOutputTokens": max_tokens},
+    }
+
+
+def call_api(
+    provider: str,
+    api_key: str,
+    model: str,
+    max_tokens: int,
+    agents_content: str,
+    doc_content: str,
+    doc_file: str,
+    commit_prefix: str,
+    output_format: str = "text",
+    include_diff_markers: bool = False,
+    verbose: bool = False,
+    timeout: int = 120,
+) -> tuple[str, TokenUsage]:
+    """Build the per-provider request body and dispatch via _common."""
+    if provider == "anthropic":
+        request_data = build_anthropic_request(
+            model,
+            max_tokens,
+            agents_content,
+            doc_content,
+            doc_file,
+            commit_prefix,
+            output_format,
+            include_diff_markers,
+        )
+    elif provider == "google":
+        request_data = build_google_request(
+            max_tokens,
+            agents_content,
+            doc_content,
+            doc_file,
+            commit_prefix,
+            output_format,
+            include_diff_markers,
+        )
+    else:  # openai, xai
+        request_data = build_openai_request(
+            model,
+            max_tokens,
+            agents_content,
+            doc_content,
+            doc_file,
+            commit_prefix,
+            output_format,
+            include_diff_markers,
+        )
+    return send_request(
+        provider,
+        api_key,
+        model,
+        request_data,
+        timeout=timeout,
+        verbose=verbose,
+    )
+
+
+def parse_review_text(review_text: str) -> tuple[str, str]:
+    """Extract commit message and diff from text format response."""
+    commit_msg = ""
+    diff = ""
+
+    # Extract commit message
+    msg_match = re.search(
+        r"---COMMIT_MESSAGE_START---\s*\n(.*?)\n---COMMIT_MESSAGE_END---",
+        review_text,
+        re.DOTALL,
+    )
+    if msg_match:
+        commit_msg = msg_match.group(1).strip()
+
+    # Extract unified diff
+    diff_match = re.search(
+        r"---UNIFIED_DIFF_START---\s*\n(.*?)\n---UNIFIED_DIFF_END---",
+        review_text,
+        re.DOTALL,
+    )
+    if diff_match:
+        diff = diff_match.group(1).strip()
+        # Clean up any markdown code fence if present
+        diff = re.sub(r"^```diff\s*\n?", "", diff)
+        diff = re.sub(r"\n?```\s*$", "", diff)
+
+    return commit_msg, diff
+
+
+def strip_diff_markers(text: str) -> str:
+    """Remove the diff/msg extraction markers from text."""
+    # Remove commit message markers and content
+    text = re.sub(
+        r"\n*---COMMIT_MESSAGE_START---\s*\n.*?\n---COMMIT_MESSAGE_END---\s*",
+        "",
+        text,
+        flags=re.DOTALL,
+    )
+    # Remove unified diff markers and content
+    text = re.sub(
+        r"\n*---UNIFIED_DIFF_START---\s*\n.*?\n---UNIFIED_DIFF_END---\s*",
+        "",
+        text,
+        flags=re.DOTALL,
+    )
+    return text.strip()
+
+
+def send_email(
+    to_addrs: list[str],
+    cc_addrs: list[str],
+    from_addr: str,
+    subject: str,
+    in_reply_to: str | None,
+    body: str,
+    dry_run: bool = False,
+    verbose: bool = False,
+) -> None:
+    """Send review email via SMTP using git sendemail config.
+
+    TODO: This duplicates send_email in analyze-patch.py, which uses the
+    git send-email / sendmail / msmtp fallback chain instead of direct
+    smtplib. Both approaches work; pick one and move it to _common.py.
+    """
+    # Build email message
+    msg = EmailMessage()
+    msg["From"] = from_addr
+    msg["To"] = ", ".join(to_addrs)
+    if cc_addrs:
+        msg["Cc"] = ", ".join(cc_addrs)
+    msg["Subject"] = subject
+    if in_reply_to:
+        msg["In-Reply-To"] = in_reply_to
+        msg["References"] = in_reply_to
+    msg.set_content(body)
+
+    if dry_run:
+        print("=== Email Preview (dry-run) ===", file=sys.stderr)
+        print(msg.as_string(), file=sys.stderr)
+        print("=== End Preview ===", file=sys.stderr)
+        return
+
+    # Get SMTP configuration from git config
+    smtp_config = get_smtp_config()
+
+    if not smtp_config["server"]:
+        error("No SMTP server configured. Set git config sendemail.smtpserver")
+
+    server = smtp_config["server"]
+    port = smtp_config["port"]
+    user = smtp_config["user"]
+    encryption = smtp_config["encryption"]
+
+    # Get password from environment or git config, or prompt
+    password = os.environ.get("SMTP_PASSWORD") or smtp_config["password"]
+    if user and not password:
+        password = getpass.getpass(f"SMTP password for {user}@{server}: ")
+
+    if verbose:
+        print(f"SMTP server: {server}:{port}", file=sys.stderr)
+        print(f"SMTP user: {user or '(none)'}", file=sys.stderr)
+        print(f"Encryption: {encryption or 'starttls'}", file=sys.stderr)
+
+    # Collect all recipients
+    all_recipients = list(to_addrs)
+    if cc_addrs:
+        all_recipients.extend(cc_addrs)
+
+    try:
+        if encryption == "ssl":
+            # SSL/TLS connection from the start (port 465)
+            context = ssl.create_default_context()
+            with smtplib.SMTP_SSL(server, port, context=context) as smtp:
+                if user and password:
+                    smtp.login(user, password)
+                smtp.send_message(msg, from_addr, all_recipients)
+        else:
+            # STARTTLS (port 587) or plain (port 25)
+            with smtplib.SMTP(server, port) as smtp:
+                smtp.ehlo()
+                if encryption == "tls" or port == 587:
+                    context = ssl.create_default_context()
+                    smtp.starttls(context=context)
+                    smtp.ehlo()
+                if user and password:
+                    smtp.login(user, password)
+                smtp.send_message(msg, from_addr, all_recipients)
+
+        print(f"Email sent via SMTP ({server}:{port})", file=sys.stderr)
+
+    except smtplib.SMTPAuthenticationError as e:
+        error(f"SMTP authentication failed: {e}")
+    except smtplib.SMTPException as e:
+        error(f"SMTP error: {e}")
+    except OSError as e:
+        error(f"Connection error to {server}:{port}: {e}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Review DPDK documentation files using AI providers. "
+        "Accepts multiple files and generates output for each.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    %(prog)s doc/guides/prog_guide/mempool_lib.rst
+    %(prog)s doc/guides/nics/*.rst              # Review all NIC docs
+    %(prog)s -p openai -o /tmp doc/guides/nics/ixgbe.rst doc/guides/nics/i40e.rst
+    %(prog)s -f html -d -o /tmp/reviews doc/guides/nics/*.rst  # HTML + diff files
+    %(prog)s -f json -o /tmp doc/guides/howto/flow_bifurcation.rst
+    %(prog)s --send-email --to [email protected] doc/guides/nics/ixgbe.rst
+
+Output files (in output-dir):
+    <basename>.txt|.md|.html|.json  Review in selected format
+    <basename>.diff                  Unified diff (text/json, or with --diff)
+    <basename>.msg                   Commit message (text/json, or with --diff)
+
+After review:
+    git apply <basename>.diff
+    git commit -sF <basename>.msg
+
+SMTP Configuration (from git config):
+    sendemail.smtpserver      SMTP server hostname
+    sendemail.smtpserverport  SMTP port (default: 587 for TLS, 465 for SSL)
+    sendemail.smtpuser        SMTP username
+    sendemail.smtpencryption  'tls' for STARTTLS, 'ssl' for SSL/TLS
+    sendemail.smtppass        SMTP password (or set SMTP_PASSWORD env var)
+
+Example git config:
+    git config --global sendemail.smtpserver smtp.gmail.com
+    git config --global sendemail.smtpserverport 587
+    git config --global sendemail.smtpuser [email protected]
+    git config --global sendemail.smtpencryption tls
+
+Token Usage:
+    Use --show-tokens (or -v/--verbose) to print a token usage summary
+    on stderr after the run. Off by default.
+        """,
+    )
+
+    parser.add_argument(
+        "doc_files",
+        nargs="+",
+        metavar="doc_file",
+        help="Documentation file(s) to review",
+    )
+    parser.add_argument(
+        "-p",
+        "--provider",
+        choices=PROVIDERS.keys(),
+        default="anthropic",
+        help="AI provider (default: anthropic)",
+    )
+    parser.add_argument(
+        "-a",
+        "--agents",
+        default="AGENTS.md",
+        help="Path to AGENTS.md file (default: AGENTS.md)",
+    )
+    parser.add_argument(
+        "-m",
+        "--model",
+        help="Model to use (default: provider-specific)",
+    )
+    parser.add_argument(
+        "-t",
+        "--tokens",
+        type=int,
+        default=8192,
+        help="Max tokens for response (default: 8192)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output-dir",
+        default=".",
+        help="Output directory for all output files (default: .)",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Show API request details",
+    )
+    add_token_args(parser)
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="Suppress review output to stdout (only write files)",
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        choices=FORMAT_EXTENSIONS,
+        default="text",
+        dest="output_format",
+        help="Output format: text, markdown, html, json (default: text)",
+    )
+    parser.add_argument(
+        "-d",
+        "--diff",
+        action="store_true",
+        help="Always produce .diff and .msg files (automatic for text/json)",
+    )
+    parser.add_argument(
+        "-l",
+        "--list-providers",
+        action="store_true",
+        help="List available providers and exit",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=120,
+        metavar="SECONDS",
+        help="API request timeout in seconds (default: 120)",
+    )
+
+    # Email options
+    email_group = parser.add_argument_group("Email Options")
+    email_group.add_argument(
+        "--send-email",
+        action="store_true",
+        help="Send review via email",
+    )
+    email_group.add_argument(
+        "--to",
+        action="append",
+        dest="to_addrs",
+        default=[],
+        metavar="ADDRESS",
+        help="Email recipient (can be specified multiple times)",
+    )
+    email_group.add_argument(
+        "--cc",
+        action="append",
+        dest="cc_addrs",
+        default=[],
+        metavar="ADDRESS",
+        help="CC recipient (can be specified multiple times)",
+    )
+    email_group.add_argument(
+        "--from",
+        dest="from_addr",
+        metavar="ADDRESS",
+        help="From address (default: from git config)",
+    )
+    email_group.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show email without sending",
+    )
+
+    args = parser.parse_args()
+
+    if args.list_providers:
+        list_providers()
+
+    # Get provider config
+    config = PROVIDERS[args.provider]
+    model = args.model or config["default_model"]
+
+    # Get API key
+    api_key = os.environ.get(config["env_var"])
+    if not api_key:
+        error(f"{config['env_var']} environment variable not set")
+
+    # Validate files
+    agents_path = Path(args.agents)
+    if not agents_path.exists():
+        error(f"AGENTS.md not found: {args.agents}")
+
+    # Validate all doc files exist before processing
+    doc_paths = []
+    for doc_file in args.doc_files:
+        doc_path = Path(doc_file)
+        if not doc_path.exists():
+            error(f"Documentation file not found: {doc_file}")
+        doc_paths.append((doc_file, doc_path))
+
+    # Validate email options
+    if args.send_email and not args.to_addrs:
+        error("--send-email requires at least one --to address")
+
+    # Get from address for email
+    from_addr = args.from_addr
+    if args.send_email and not from_addr:
+        git_name = get_git_config("user.name")
+        git_email = get_git_config("user.email")
+        if git_email:
+            from_addr = f"{git_name} <{git_email}>" if git_name else git_email
+        else:
+            error("No --from specified and git user.email not configured")
+
+    # Read AGENTS.md once
+    # AGENTS.md should always be UTF-8; replace bad bytes rather than crash.
+    agents_content = agents_path.read_text(encoding="utf-8", errors="replace")
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    provider_name = config["name"]
+
+    # Accumulate token usage across all API calls
+    total_usage = TokenUsage()
+
+    # Process each file
+    num_files = len(doc_paths)
+    for file_idx, (doc_file, doc_path) in enumerate(doc_paths, 1):
+        if num_files > 1:
+            print(
+                f"\n{'=' * 60}",
+                file=sys.stderr,
+            )
+            print(
+                f"Processing file {file_idx}/{num_files}: {doc_file}",
+                file=sys.stderr,
+            )
+            print(
+                f"{'=' * 60}",
+                file=sys.stderr,
+            )
+
+        # Determine output filenames
+        doc_basename = doc_path.stem
+        diff_file = output_dir / f"{doc_basename}.diff"
+        msg_file = output_dir / f"{doc_basename}.msg"
+
+        # Get commit prefix
+        commit_prefix = get_commit_prefix(doc_file)
+
+        # Read doc content
+        # Docs should be UTF-8 (.rst, .md, etc.); be defensive about bad bytes.
+        doc_content = doc_path.read_text(encoding="utf-8", errors="replace")
+
+        if args.verbose:
+            print("=== Request ===", file=sys.stderr)
+            print(f"Provider: {args.provider}", file=sys.stderr)
+            print(f"Model: {model}", file=sys.stderr)
+            print(f"Output format: {args.output_format}", file=sys.stderr)
+            print(f"AGENTS file: {args.agents}", file=sys.stderr)
+            print(f"Doc file: {doc_file}", file=sys.stderr)
+            print(f"Commit prefix: {commit_prefix}", file=sys.stderr)
+            print(f"Output dir: {args.output_dir}", file=sys.stderr)
+            if args.send_email:
+                print("Send email: yes", file=sys.stderr)
+                print(f"To: {', '.join(args.to_addrs)}", file=sys.stderr)
+                if args.cc_addrs:
+                    print(f"Cc: {', '.join(args.cc_addrs)}", file=sys.stderr)
+                print(f"From: {from_addr}", file=sys.stderr)
+            print("===============", file=sys.stderr)
+
+        # Call API
+        review_text, call_usage = call_api(
+            args.provider,
+            api_key,
+            model,
+            args.tokens,
+            agents_content,
+            doc_content,
+            doc_file,
+            commit_prefix,
+            args.output_format,
+            args.diff,
+            args.verbose,
+            args.timeout,
+        )
+        total_usage.add(call_usage)
+
+        if not review_text:
+            print(
+                f"Warning: No response received for {doc_file}",
+                file=sys.stderr,
+            )
+            continue
+
+        # Determine review output file
+        format_ext = FORMAT_EXTENSIONS[args.output_format]
+        review_file = output_dir / f"{doc_basename}{format_ext}"
+
+        # Determine if we should write diff/msg files
+        write_diff_msg = args.diff or args.output_format in ("text", "json")
+
+        # Extract commit message and diff first (before stripping markers)
+        commit_msg, diff = "", ""
+        if write_diff_msg:
+            if args.output_format == "json":
+                # Will extract from JSON below
+                pass
+            else:
+                # Parse from text format markers
+                commit_msg, diff = parse_review_text(review_text)
+
+        # For non-text formats with --diff, strip the markers from display output
+        display_text = review_text
+        if args.diff and args.output_format in ("markdown", "html"):
+            display_text = strip_diff_markers(review_text)
+
+        # Build formatted output text
+        if args.output_format == "text":
+            output_text = review_text
+        elif args.output_format == "json":
+            # Try to parse JSON response
+            try:
+                review_data = json.loads(review_text)
+            except json.JSONDecodeError:
+                print("Warning: Response is not valid JSON", file=sys.stderr)
+                review_data = {"raw_response": review_text}
+
+            # Extract diff/msg from JSON if present
+            if write_diff_msg:
+                if isinstance(review_data, dict) and "raw_response" not in review_data:
+                    commit_msg = review_data.get("commit_message", "")
+                    diff = review_data.get("diff", "")
+
+            # Add metadata
+            usage_data = {
+                "api_calls": call_usage.api_calls,
+                "input_tokens": call_usage.input_tokens,
+                "output_tokens": call_usage.output_tokens,
+                "total_tokens": call_usage.input_tokens + call_usage.output_tokens,
+            }
+            if call_usage.cache_creation_tokens:
+                usage_data["cache_creation_tokens"] = call_usage.cache_creation_tokens
+            if call_usage.cache_read_tokens:
+                usage_data["cache_read_tokens"] = call_usage.cache_read_tokens
+
+            output_data = {
+                "metadata": {
+                    "doc_file": doc_file,
+                    "provider": args.provider,
+                    "provider_name": provider_name,
+                    "model": model,
+                    "commit_prefix": commit_prefix,
+                    "token_usage": usage_data,
+                },
+                "review": review_data,
+            }
+            output_text = json.dumps(output_data, indent=2)
+        elif args.output_format == "markdown":
+            output_text = f"""# Documentation Review: {doc_path.name}
+
+*Reviewed by {provider_name} ({model})*
+
+{display_text}
+"""
+        elif args.output_format == "html":
+            output_text = f"""<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>Review: {doc_path.name}</title>
+<style>
+body {{ font-family: system-ui, sans-serif; max-width: 900px; margin: 2em auto; padding: 0 1em; }}
+h1 {{ color: #333; }}
+.review-meta {{ color: #666; font-style: italic; }}
+pre {{ background: #f5f5f5; padding: 1em; overflow-x: auto; }}
+</style>
+</head>
+<body>
+<h1>Documentation Review: {doc_path.name}</h1>
+<p class="review-meta">Reviewed by {provider_name} ({model})</p>
+<div class="review-content">
+{display_text}
+</div>
+</body>
+</html>
+"""
+
+        # Write formatted review to file
+        review_file.write_text(output_text)
+        print(f"Review written to: {review_file}", file=sys.stderr)
+
+        # Write diff/msg files
+        if write_diff_msg:
+            if commit_msg:
+                msg_file.write_text(commit_msg + "\n")
+                print(f"Commit message written to: {msg_file}", file=sys.stderr)
+            else:
+                msg_file.write_text("# No commit message generated\n")
+                print("Warning: Could not extract commit message", file=sys.stderr)
+
+            if diff:
+                diff_file.write_text(diff + "\n")
+                print(f"Diff written to: {diff_file}", file=sys.stderr)
+            else:
+                diff_file.write_text("# No changes suggested\n")
+                print("Warning: Could not extract diff", file=sys.stderr)
+
+        # Print to stdout unless quiet (or multiple files without verbose)
+        show_stdout = not args.quiet and (num_files == 1 or args.verbose)
+        if show_stdout:
+            print(
+                f"\n=== Documentation Review: {doc_path.name} "
+                f"(via {provider_name}) ==="
+            )
+            print(output_text)
+
+            # Print usage instructions for text format
+            if args.output_format == "text":
+                print("\n=== Output Files ===")
+                print(f"Commit message: {msg_file}")
+                print(f"Diff file:      {diff_file}")
+                print("\nTo apply changes:")
+                print(f"  git apply {diff_file}")
+                print(f"  git commit -sF {msg_file}")
+
+        # Send email if requested
+        if args.send_email:
+            if args.output_format != "text":
+                print(
+                    f"Note: Email will be sent as plain text regardless of "
+                    f"--format={args.output_format}",
+                    file=sys.stderr,
+                )
+
+            review_subject = f"[REVIEW] {commit_prefix} {doc_path.name}"
+
+            # Build email body
+            email_body = f"""AI-generated documentation review of {doc_file}
+Reviewed using {provider_name} ({model})
+
+This is an automated review. Please verify all suggestions.
+
+---
+
+{review_text}
+"""
+
+            if args.verbose:
+                print("", file=sys.stderr)
+                print("=== Email Details ===", file=sys.stderr)
+                print(f"Subject: {review_subject}", file=sys.stderr)
+                print("=====================", file=sys.stderr)
+
+            send_email(
+                args.to_addrs,
+                args.cc_addrs,
+                from_addr,
+                review_subject,
+                None,
+                email_body,
+                args.dry_run,
+                args.verbose,
+            )
+
+            if not args.dry_run:
+                print("", file=sys.stderr)
+                print(f"Review sent to: {', '.join(args.to_addrs)}", file=sys.stderr)
+
+    # Print summary for multiple files
+    if num_files > 1:
+        print(f"\n{'=' * 60}", file=sys.stderr)
+        print(f"Processed {num_files} files", file=sys.stderr)
+        print(f"Output directory: {output_dir}", file=sys.stderr)
+
+    print_token_summary(
+        total_usage,
+        args.provider,
+        model,
+        args.show_tokens or args.verbose,
+    )
+
+
+if __name__ == "__main__":
+    main()