# xilinx/xilinxvirtualcable architecture

> Architecture diagram of the GitHub repository xilinx/xilinxvirtualcable, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xilinx/xilinxvirtualcable
- Repository: https://github.com/xilinx/xilinxvirtualcable

## Overview

##### Project Type and Purpose
- This is an open-source, C-based network-server tool (Xilinx Virtual Cable, XVC) that implements a TCP/IP service to emulate a JTAG cable.
- It allows EDA tools (e.g., Vivado Logic Analyzer) or custom TCP clients to perform JTAG operations (shift, getinfo) and, in version 1.1, memory reads/writes (mrd, mwr) over a network.
- The project supplies multiple platform-specific server implementations:
- dpc/         – XVC 1.1 via the Debug Packet Controller interface
- jtag/zynq7000 – XVC 1.0 on Zynq-7000 SoCs
- jtag/zynqMP   – XVC 1.0 on Zynq UltraScale+ SoCs (with a Linux kernel driver)
- mem/versal    – XVC 1.1 on Versal SoCs (memory-mapped RD/WR)

##### File-Structure Analysis
- Top level
- README.md – high-level description, protocol details
- dpc/     – source, headers, Makefile, license for XVC 1.1 via DPC
- jtag/    – two subdirs for Zynq7000 (XAPP1251 reference design) and ZynqMP
- mem/     – Versal XVC 1.1 memory server
- Each platform folder contains:
- src/ or driver/ and user/ subfolders
- C source for a TCP server (xvcserver.c), hardware access modules (hsdp_lib.c, xvc_mem.c, xvc_driver.c)
- Build scripts (Makefile) and configuration headers
- Key patterns
- Protocol-handler layer (parse TCP messages, respond per XVC 1.0/1.1)
- Platform-abstraction layer (DPC library, kernel driver or memory access routines)
- Hardware interface layer (JTAG pins, debug packet controller, SoC memory bus)

##### README Insights
- Describes XVC 1.0 vs. 1.1 messages and command set
- Emphasizes single-connection, request/response model over TCP
- Points to platform examples and reference designs (e.g., XAPP1251 for Zynq-7000)

##### Diagramming the Architecture
a. Main Components
1. External Client (Vivado, custom TCP client)
2. TCP/IP Stack (BSD sockets in C)
3. XVC Server Process
- Protocol Handler (parses getinfo, settck, shift, mrd, mwr)
- Command Dispatcher (routes commands to HAL)
4. Platform-Specific HAL Modules
- DPC Library (hsdp.c/h)
- JTAG Kernel Driver Interface (xvc_driver + ioctl)
- Memory-Mapped Access (xvc_mem)
5. Hardware Interfaces
- Debug Packet Controller IP
- SoC JTAG pins (via EMIO/PL)
- SoC memory bus for mrd/mwr
6. Physical FPGA/SoC Device
b. Relationships and Data Flows
- Client → TCP Socket → XVC Server → Protocol Handler
- Protocol Handler ──> Dispatcher → Platform HAL → Hardware
- Hardware response → HAL → Protocol Handler → TCP Socket → Client
c. Architectural Patterns
- Layered architecture: Network → Protocol → HAL → Hardware
- Strategy pattern for selecting platform HAL at build/run time
- Single-threaded, synchronous request/response model (no concurrent clients)
d. Key Technologies
- C programming, Makefiles
- BSD sockets API for TCP/IP
- Linux kernel driver (for ZynqMP) via char device and ioctl
- ULEB128 encoding for mrd/mwr parameters
- Build tools: GNU Make, cross-compile toolchains

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Network Layer
    Client["External Client\n(Vivado or TCP Client)"]:::network
    TCP["TCP Socket\n(BSD Sockets)"]:::network

    Client -->|"connect"| TCP

    %% Protocol Layer
    subgraph "Protocol Layer"
        direction TB
        DPC_Server["XVC Server\n(DPC Variant)"]:::protocol
        Z7_Server["XVC Server\n(Zynq-7000)"]:::protocol
        ZMP_Usr_Server["XVC Server\n(ZynqMP User)"]:::protocol
        Versal_Server["XVC Server\n(Versal)"]:::protocol
        ProtocolDispatch["Command Dispatcher"]:::protocol
    end

    TCP --> DPC_Server
    TCP --> Z7_Server
    TCP --> ZMP_Usr_Server
    TCP --> Versal_Server

    DPC_Server --> ProtocolDispatch
    Z7_Server --> ProtocolDispatch
    ZMP_Usr_Server --> ProtocolDispatch
    Versal_Server --> ProtocolDispatch

    %% HAL Layer
    subgraph "HAL Layer"
        direction TB
        DPC_HAL["DPC HAL"]:::hal
        Z7_HAL["JTAG HAL\n(Zynq-7000)"]:::hal
        ZMP_Usr_HAL["User HAL\n(ZynqMP)"]:::hal
        ZMP_Kern_HAL["Kernel Driver HAL\n(ZynqMP)"]:::hal
        Versal_HAL["Memory-Mapped HAL\n(Versal)"]:::hal
    end

    ProtocolDispatch --> DPC_HAL
    ProtocolDispatch --> Z7_HAL
    ProtocolDispatch --> ZMP_Usr_HAL
    ZMP_Usr_HAL --> ZMP_Kern_HAL
    ProtocolDispatch --> Versal_HAL

    %% Hardware Layer
    subgraph "Hardware Interfaces"
        direction TB
        DPC_HW["Debug Packet Controller IP"]:::hardware
        JTAG_HW["SoC JTAG Pins"]:::hardware
        MEM_BUS["SoC Memory Bus"]:::hardware
    end

    DPC_HAL --> DPC_HW
    Z7_HAL --> JTAG_HW
    ZMP_Kern_HAL --> JTAG_HW
    Versal_HAL --> MEM_BUS

    %% Physical Device
    subgraph "Physical FPGA/SoC Device"
        Physical["FPGA/SoC Device"]:::hardware
    end

    DPC_HW --> Physical
    JTAG_HW --> Physical
    MEM_BUS --> Physical

    %% Click Events
    click DPC_Server "https://github.com/xilinx/xilinxvirtualcable/blob/master/dpc/src/xvcserver.c"
    click DPC_Server "https://github.com/xilinx/xilinxvirtualcable/blob/master/dpc/src/xvcserver.h"
    click DPC_HAL "https://github.com/xilinx/xilinxvirtualcable/blob/master/dpc/src/hsdp.c"
    click DPC_HAL "https://github.com/xilinx/xilinxvirtualcable/blob/master/dpc/src/hsdp.h"
    click DPC_HAL "https://github.com/xilinx/xilinxvirtualcable/blob/master/dpc/src/hsdp_lib.c"
    click DPC_HAL "https://github.com/xilinx/xilinxvirtualcable/blob/master/dpc/src/hsdp_lib.h"
    click DPC_HAL "https://github.com/xilinx/xilinxvirtualcable/blob/master/dpc/src/xvc_dpc.c"
    click Z7_Server "https://github.com/xilinx/xilinxvirtualcable/blob/master/jtag/zynq7000/XAPP1251/src/xvcServer.c"
    click ZMP_Usr_Server "https://github.com/xilinx/xilinxvirtualcable/blob/master/jtag/zynqMP/src/user/xvcServer.c"
    click ZMP_Kern_HAL "https://github.com/xilinx/xilinxvirtualcable/blob/master/jtag/zynqMP/src/driver/xvc_driver.c"
    click ZMP_Kern_HAL "https://github.com/xilinx/xilinxvirtualcable/blob/master/jtag/zynqMP/src/driver/xvc_driver.h"
    click ZMP_Kern_HAL "https://github.com/xilinx/xilinxvirtualcable/blob/master/jtag/zynqMP/src/driver/xvc_driver_base.c"
    click ZMP_Kern_HAL "https://github.com/xilinx/xilinxvirtualcable/blob/master/jtag/zynqMP/src/driver/xvc_ioctl.h"
    click Versal_Server "https://github.com/xilinx/xilinxvirtualcable/blob/master/mem/versal/src/xvcserver.c"
    click Versal_Server "https://github.com/xilinx/xilinxvirtualcable/blob/master/mem/versal/src/xvcserver.h"
    click Versal_HAL "https://github.com/xilinx/xilinxvirtualcable/blob/master/mem/versal/src/xvc_mem.c"

    %% Styles
    classDef network fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef protocol fill:#d4edda,stroke:#333,stroke-width:1px
    classDef hal fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef hardware fill:#e2e3e5,stroke:#333,stroke-width:1px
```
