XDS110 MCP Server

# Product Requirements Document (PRD) ## XDS110 MCP Server - LLM Co-Debugger for TI Embedded Systems **Version:** 1.0 **Date:** 2025-01-21 **Status:** Active Development --- ## Executive Summary The XDS110 MCP Server is an MCP (Model Context Protocol) implementation that enables Large Language Models to function as intelligent co-debuggers for Texas Instruments embedded systems. The server provides real-time variable monitoring, direct memory manipulation, and domain-specific analysis capabilities through an OpenOCD multi-client proxy architecture. This represents the first MCP server specifically designed for embedded systems debugging, addressing the critical need for intelligent debugging assistance in complex motor control and embedded applications. --- ## Problem Statement ### Current Debugging Challenges Embedded systems debugging, particularly for motor control applications, presents several challenges: 1. **Exclusive Hardware Access**: Traditional debugging tools allow only one connection to debug hardware, preventing simultaneous use of different debugging approaches 2. **Manual Variable Analysis**: Engineers must manually monitor and correlate dozens of variables during debugging sessions 3. **Domain Knowledge Gap**: Complex motor control principles (FOC, alignment procedures, fault analysis) are not readily accessible during debugging 4. **Time-Intensive Troubleshooting**: Issues like motor humming, overcurrent faults, and calibration problems require extensive manual analysis ### Specific Technical Problems - **Motor Humming During Bypass Alignment**: PMSM motors hum instead of spinning during bypass alignment sequences, requiring analysis of bypass variables, current control initialization, and encoder states - **Complex State Machine Debugging**: Motor control state machines (IDLE → ALIGNMENT → CTRL_RUN) require simultaneous monitoring of multiple variables - **Memory Structure Access**: Direct manipulation of embedded union structures (like debug_bypass) is limited by debugger expression evaluation capabilities - **Real-Time Analysis**: Need for continuous monitoring with intelligent pattern recognition and anomaly detection --- ## Solution Architecture ### System Architecture ``` ┌─────────────────┐ ┌──────────────┐ ┌─────────────┐ │ LLM Client │◄──►│ MCP Server │◄──►│ OpenOCD │ │ (Claude/GPT) │ │ (Python) │ │ Proxy │ └─────────────────┘ └──────────────┘ └─────────────┘ │ │ ▼ ▼ ┌──────────────────┐ ┌─────────────┐ │ Domain Knowledge │ │ XDS110 │ │ • Motor Control │ │ Debug Probe │ │ • TI Peripherals │ └─────────────┘ │ • Fault Patterns │ │ └──────────────────┘ ▼ ┌─────────────┐ │ TMS320F280 │ │ Target │ └─────────────┘ ``` ### Key Technical Innovation: OpenOCD Multi-Client Proxy The solution leverages OpenOCD's multi-client capabilities to overcome hardware access limitations: 1. **Single Hardware Connection**: OpenOCD connects to XDS110 using native driver support 2. **Multiple Client Support**: OpenOCD's GDB server supports multiple simultaneous connections via `-gdb-max-connections` 3. **Intelligent GDB Client**: MCP server acts as a specialized GDB client with domain knowledge 4. **CCS Compatibility**: Code Composer Studio can connect through session handoff mechanism **Research Foundation:** - [OpenOCD Multi-Client Documentation](https://openocd.org/doc/html/GDB-and-OpenOCD.html) - [XDS110 Native OpenOCD Support](https://github.com/openocd-org/openocd/blob/master/src/jtag/drivers/xds110.c) - [Verified TI Forum Examples](https://e2e.ti.com/support/tools/code-composer-studio-group/ccs/f/code-composer-studio-forum/630450/tms570ls3137-using-xds110-with-gdb-openocd) --- ## Technical Requirements ### Functional Requirements #### Core MCP Tools | Tool Name | Description | Parameters | Implementation Priority | |-----------|-------------|------------|------------------------| | `read_variables` | Read motor control variable values | `variable_list`, `format` | P0 - Critical | | `monitor_variables` | Continuous variable monitoring with change detection | `variables`, `duration`, `threshold` | P0 - Critical | | `write_memory` | Direct memory writes to structures/addresses | `address`, `value`, `size` | P0 - Critical | | `set_breakpoint` | Conditional breakpoints with custom logic | `address`, `condition`, `action` | P1 - Important | | `analyze_motor_state` | Domain-specific motor analysis | `focus_area` | P1 - Important | | `calibrate_motor` | Motor calibration sequence control | `calibration_type` | P2 - Nice to have | #### Domain Knowledge Integration **Motor Control Expertise:** - FOC (Field-Oriented Control) principles and fault patterns - PMSM motor characteristics and behavior analysis - Motor state machine transitions (IDLE → ALIGNMENT → CTRL_RUN → CL_RUNNING) - Encoder systems (absolute vs quadrature) and calibration procedures **TI Peripheral Knowledge:** - TMS320F280039C memory layout and register mappings - debug_bypass structure layout and union field access - Motor control variable schemas and relationships - Common fault conditions and diagnostic approaches #### Hardware Interface Requirements **Verified Configurations:** - TI XDS110 Debug Probe (USB connection) - TMS320F280039C microcontroller - Custom boards with XDS110 debugger integration - PMSM motor control via DRV8323RH driver - Direct memory access to union structures at 0x0000d3c0 **OpenOCD Integration:** - XDS110 firmware version 2.3.0.11+ required - Native `adapter driver xds110` configuration - Multi-client GDB server with configurable port assignment - JTAG transport selection with appropriate speed settings ### Performance Requirements | Metric | Requirement | Measurement Method | |--------|-------------|-------------------| | Variable Read Latency | < 100ms per variable | GDB command timing | | Monitoring Frequency | Up to 10Hz for critical variables | Continuous monitoring loops | | Memory Footprint | < 50MB RAM usage | Process memory monitoring | | Startup Time | < 5 seconds to ready state | MCP server initialization | | Connection Recovery | Auto-reconnect within 1 second | Hardware disconnect testing | | Concurrent Connections | Support 2-3 LLM clients | Multi-client stress testing | ### Reliability Requirements **Connection Management:** - Graceful handling of hardware disconnections - Automatic OpenOCD process recovery - Session persistence across brief interruptions - Fault tolerance with partial variable access failures **Error Handling:** - Comprehensive GDB protocol error handling - Hardware lock-up detection and recovery - Invalid memory access protection - Logging and diagnostic information for troubleshooting **Security Requirements:** - Local-only binding by default (localhost) - Memory write access limited to safe regions - Audit logging for all memory modification operations - Optional authentication for MCP client connections --- ## Implementation Plan ### Phase 1: Foundation (4 weeks) **Objective:** Establish basic MCP server with OpenOCD connectivity **Deliverables:** - [ ] MCP server framework using Python SDK - [ ] OpenOCD integration with XDS110 support - [ ] Basic GDB protocol communication - [ ] Variable reading functionality - [ ] Hardware connection validation **Success Criteria:** - MCP server responds to basic tool calls - OpenOCD successfully connects to XDS110 hardware - LLM can read motor control variables - Sub-200ms response time for variable queries **Technical Milestones:** - OpenOCD configuration for F280039C target - GDB client implementation with error handling - MCP tool registration and basic functionality - Hardware detection and validation utilities ### Phase 2: Core Functionality (6 weeks) **Objective:** Implement essential debugging and analysis capabilities **Deliverables:** - [ ] Real-time variable monitoring with change detection - [ ] Direct memory write capabilities - [ ] Motor control domain knowledge integration - [ ] Session handoff with Code Composer Studio - [ ] Comprehensive error handling and logging **Success Criteria:** - Successfully diagnose motor humming issues - LLM can modify motor control parameters via memory writes - Pattern recognition identifies common fault conditions - Seamless switching between CCS and MCP debugging modes **Technical Milestones:** - Memory access to debug_bypass structure (0x0000d3c0) - Variable schema definition and management - Domain knowledge database implementation - Session management and conflict resolution ### Phase 3: Advanced Analysis (4 weeks) **Objective:** Intelligent pattern recognition and automated diagnosis **Deliverables:** - [ ] Fault pattern recognition algorithms - [ ] Automated motor behavior analysis - [ ] Performance optimization and caching - [ ] Extended hardware support validation - [ ] Comprehensive testing suite **Success Criteria:** - 90% accuracy for known motor control fault patterns - Automated identification of calibration issues - Performance meets sub-100ms latency requirements - Reliable operation across extended testing scenarios **Technical Milestones:** - Machine learning integration for pattern recognition - Performance profiling and optimization - Extended hardware compatibility testing - Integration with existing ti_debugger scripts ### Phase 4: Production Readiness (3 weeks) **Objective:** Production deployment and documentation **Deliverables:** - [ ] Complete documentation and user guides - [ ] Installation automation and validation - [ ] Security audit and hardening - [ ] Community contribution guidelines - [ ] Release packaging and distribution **Success Criteria:** - Complete user documentation available - Installation process takes < 10 minutes - Security review completed without critical issues - Ready for open source community contribution --- ## Risk Assessment ### Technical Risks **OpenOCD Compatibility (High Risk)** - **Risk:** XDS110 + OpenOCD integration limitations or undocumented issues - **Mitigation:** Early proof-of-concept validation, fallback to DSS-only approach - **Contingency:** Implement session handoff without concurrent access **GDB Protocol Performance (Medium Risk)** - **Risk:** GDB command overhead limiting real-time performance requirements - **Mitigation:** Command batching, local caching, and connection pooling - **Contingency:** Reduce monitoring frequency to acceptable performance levels **Hardware Lock-up Recovery (Medium Risk)** - **Risk:** Target device lock-up during memory modifications by LLM - **Mitigation:** Safe memory region definitions, recovery procedures - **Contingency:** Hardware reset capability and session restoration ### Integration Risks **CCS Interaction Conflicts (Medium Risk)** - **Risk:** Unexpected behavior when switching between CCS and MCP sessions - **Mitigation:** Comprehensive testing, clear usage documentation - **Contingency:** Exclusive access mode as fallback option **Firmware Dependency Management (Low Risk)** - **Risk:** XDS110 firmware updates breaking compatibility - **Mitigation:** Version checking, compatibility matrix maintenance - **Contingency:** Support for multiple firmware versions --- ## Success Metrics ### Technical Metrics - **Variable Read Performance:** < 100ms average latency - **System Reliability:** < 1% unexpected disconnection rate - **Memory Efficiency:** < 50MB RAM footprint - **Startup Performance:** < 5 seconds to operational state ### User Experience Metrics - **Problem Resolution:** 50% reduction in debugging time for motor control issues - **Fault Identification:** 90% accuracy for known motor control problems - **Setup Time:** < 10 minutes from installation to first successful use - **Learning Curve:** Engineers productive within 1 hour of first use ### Integration Metrics - **CCS Compatibility:** Seamless handoff in 95% of test scenarios - **Hardware Compatibility:** Support for 100% of XDS110 + F280039C configurations - **Community Adoption:** Active usage by embedded systems debugging community --- ## Validation Plan ### Hardware Validation - **Primary Configuration:** Custom F280039C board + XDS110 + PMSM motor - **Motor Control Testing:** Bypass alignment, calibration sequences, parameter tuning - **Stress Testing:** Extended operation, connection recovery, fault injection - **Compatibility Testing:** Different XDS110 firmware versions, various F28xx targets ### Software Integration Testing - **MCP Protocol Compliance:** MCP Inspector validation, protocol conformance - **OpenOCD Integration:** Multi-client scenarios, session management - **LLM Integration:** Tool functionality, error handling, response formatting - **CCS Compatibility:** Session handoff, conflict resolution, state preservation ### Performance Validation - **Latency Testing:** Variable read/write timing under various load conditions - **Throughput Testing:** Maximum sustainable monitoring frequency - **Resource Testing:** Memory usage, CPU utilization, connection scaling - **Reliability Testing:** 24-hour continuous operation, error recovery --- ## Future Considerations ### Extensibility - **Additional TI MCUs:** F28xx series, C2000 family support - **Other Debug Probes:** J-Link, ST-Link compatibility - **Platform Support:** Windows and macOS compatibility - **Advanced Analytics:** Machine learning for pattern recognition ### Community Development - **Open Source Strategy:** MIT license, community contribution guidelines - **Documentation:** Comprehensive API reference, usage examples - **Plugin Architecture:** Support for custom analysis modules - **Integration Ecosystem:** IDE plugins, CI/CD integration --- ## Future Enhancements - UI Dashboard Integration ### Plotly Dash Dashboard Integration **Vision**: Transform the MCP server into a complete debugging IDE replacement with real-time visual interface. #### Core Dashboard Features - **Real-time Variable Plotting**: Stream motor control variables to interactive Plotly graphs - **Motor State Visualization**: Live state machine diagrams, encoder positions, current vectors - **Memory Inspector**: Visual memory map with structure overlays for debug_bypass - **Breakpoint Manager**: Visual breakpoint setting with code context display - **Parameter Tuning Interface**: Interactive sliders/controls for PID tuning and motor parameters #### Advanced UI Concepts - **Code Viewer Integration**: Show source code context when breakpoints are hit - Syntax highlighting for C/C++ embedded code - Variable hover values in code context - Jump to definition from variable names - **3D Motor Visualization**: Real-time 3D representation of motor position, currents, magnetic fields - **Fault Analysis Timeline**: Interactive timeline showing fault conditions and system state changes - **Calibration Wizard**: Step-by-step UI for motor calibration with visual feedback #### Technical Architecture for Dashboard ``` ┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐ │ LLM Client │ │ Plotly Dash │ │ Web Browser │ │ (Claude/GPT) │ │ Dashboard │ │ (Engineer) │ └─────────────────┘ └──────────────┘ └─────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────┐ │ XDS110 MCP Server │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │ MCP │ │ Dashboard │ │ Data Streaming │ │ │ │ Tools │ │ Server │ │ WebSocket │ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────┐ │ OpenOCD │ │ GDB Proxy │ └─────────────────┘ ``` #### Implementation Phases for UI Features **Phase 3A: Basic Dashboard (2 weeks)** - Real-time variable plotting with Plotly Dash - WebSocket streaming for live data updates - Basic motor state visualization - Simple parameter adjustment interface **Phase 3B: Advanced Visualization (3 weeks)** - Code viewer with breakpoint integration - 3D motor position and current visualization - Memory inspector with structure overlays - Interactive calibration interface **Phase 3C: Complete IDE Replacement (3 weeks)** - Source code debugging with syntax highlighting - Variable hover and inspection in code - Advanced fault analysis timeline - Comprehensive parameter tuning suite #### Technology Stack for Dashboard - **Frontend**: Plotly Dash with custom CSS/JS components - **Real-time Communication**: WebSocket or Server-Sent Events - **Data Streaming**: Async task queues for variable monitoring - **Code Display**: Monaco Editor (VS Code editor component) - **3D Visualization**: Plotly 3D scatter/mesh plots - **Responsive Design**: Mobile-friendly for tablet debugging #### Benefits of UI Integration - **Complete IDE Replacement**: No need for Code Composer Studio GUI - **Real-time Debugging**: Live visualization of motor behavior - **Collaborative Debugging**: Share dashboard URL with remote engineers - **Data Export**: Export plots and logs for analysis/reports - **Mobile Debugging**: Debug from tablets/phones for field work - **Training Tool**: Visual debugging for teaching embedded concepts --- ## Conclusion The XDS110 MCP Server addresses a critical gap in embedded systems debugging by providing the first MCP server specifically designed for hardware debugging applications. The technical foundation is solid, based on proven OpenOCD multi-client architecture and validated TI debugger implementations. With the addition of Plotly Dash dashboard integration, this becomes not just an MCP server, but a complete next-generation debugging IDE that combines: - **LLM Intelligence**: AI-powered debugging assistance - **Real-time Visualization**: Live motor control dashboards - **Multi-modal Interface**: Command-line, LLM chat, and visual UI - **Remote Capabilities**: Web-based debugging for distributed teams The phased development approach minimizes risk while ensuring early validation of core concepts. Success metrics focus on measurable improvements in debugging efficiency and accuracy, with clear technical performance targets. This project has the potential to significantly improve embedded systems debugging workflows and establish a new category of intelligent debugging tools for the embedded systems community.