elaphureLink

elaphureLink vendor commands extend the native CMSIS-DAP commands. All commands follow a specific binary packet format for requests and responses.

Request Packet Structure

• Prefix (8 bits): Must be 0x88 to identify an elaphureLink command.
• Command Type (8 bits): If the value is 0-127, it is the command type. If the value is 128-255, the following 2 bytes are interpreted as a 16-bit unsigned integer representing the Extended Command Type.
• Payload Length (16 bits): The length of the payload data.
• Payload Data (x bytes): Variable length data specific to the command.

Response Packet Structure

• Prefix (8 bits): Must be 0x88.
• Status (8 bits): Indicates the result of the command:
  • 0x0: Success.
  • 0x1: Execution failed.
  • 0x2: Command is pending.
  • Other values: Reserved (may be treated as failure).
• Payload Length (16 bits): The length of the response payload.
• Payload Data (x bytes): Variable length data specific to the response.

During the data transfer phase, CMSIS-DAP commands are transmitted as-is. To optimize performance, elaphureLink follows these conventions:

• Command Merging: Multiple CMSIS-DAP commands can be merged into a single packet transmission.
• Batching: Use the DAP_ExecuteCommands command to transfer multiple commands in one packet.
• Unpredictable Responses: If a client needs to send a command with an unpredictable response length, that command must be placed last in the packet and can only appear once.

This approach allows the DAP host to function with little to no modification.

elaphureLink Proxy (client)          DAP host (server)
         |                                     |
         |       REQ_CMSIS_DAP_COMMAND         |
         | ----------------------------------> |
         |                                     |
         |       RES_CMSIS_DAP_COMMAND         |
         | <---------------------------------- |
         |                                     |
         |       REQ_CMSIS_DAP_COMMAND         |
         | ----------------------------------> |
         |                                     |
         |       RES_CMSIS_DAP_COMMAND         |
         | <---------------------------------- |

elaphureLink is composed of five main functional components that facilitate remote debugging:

1. AGDI (elaphureLinkAGDI): The Application Generic Debug Interface. It serves as the bridge between Arm Keil µVision and the RDDI connection. It handles basic debugger features, complex breakpoints, flash programming, and system memory access.
2. RDDI (elaphureLinkRDDI): The Remote Device Debug Interface. It converts requests into standard CMSIS-DAP commands to allow remote DAP devices to communicate with the debug interface.
3. Proxy (elaphureLinkProxy): Communicates with the debug unit and exports APIs for connection management. Developers can use these APIs to build custom applications.
4. Wpf (elaphureLink.Wpf): A GUI wrapper for elaphureLinkProxy that provides utilities for driver management and connection control.
5. Server Providers: The physical or virtual devices (e.g., DAP probes) that implement CMSIS-DAP to provide debugging capabilities.

DbgCM provides a high-level driver template with ULINK2-equivalent functionality (Debug, Trace, Flash, and complex trace handling). To adapt DbgCM to a custom hardware debug unit, you must implement the low-level communication layer. The middle and upper layers (run/stop/step, breakpoints, watchpoints, etc.) are already implemented via Memory R/W and do not require modification.

To integrate your hardware, follow these implementation steps:

1. Communication Layer: Expose your Debug Unit's communication layer to the driver.
2. JTAG Support: Implement low-level JTAG functions in JTAG.cpp (Detect Chain, Debug/Access Port R/W, Memory R/W, Register R/W, and Sys Calls).
3. SWD Support: Implement low-level SWD functions in SWD.cpp (Debug/Access Port R/W, Memory R/W, Register R/W, and Sys Calls).
4. SWV Support: Implement low-level SWV functions in SWV.cpp (Setup, Read, Flush).
5. Detection & Selection: Implement debug unit detection and selection (JTAG/SWD) in SetupDbg.cpp (specifically within Update and OnSelchangeConfigUnit).
6. Target Lifecycle: Implement debug unit init/uninit and target detection in AGDI.cpp (InitTarget, StopTarget).
7. Target Reset: Implement target reset in AGDI.cpp (ResetTarget).

When performing firmware downloads or flashing operations between a Host and a Target device, all operations must be executed within the elaphureLink vendor scope. The standard sequence for flashing a device involves entering the vendor scope, loading the FlashOS algorithm, performing sector erasures, programming pages, and finally exiting the vendor scope.

Standard Sequence:

1. Enter vendor scope (0x2): Transitions the target into the vendor command mode.
2. Load FlashOS algorithm (0x4): Loads the necessary algorithm into the target.
3. Erase sector (0x6): Performed in a loop for each sector required.
4. Program page (0x7): Performed in a loop for each page to be written.
5. Exit vendor scope (0x3): Returns the target to its normal operating mode.

sequenceDiagram
    participant Host as Host
    participant Target as Target

    Host->>Target: Enter vendor scope (0x2)
    Target-->>Host: Acknowledge

    Host->>Target: Load FlashOS algorithm (0x4)
    Target-->>Host: Acknowledge

    loop Erase sector
        Host->>Target: Erase sector (0x6)
        Target-->>Host: Acknowledge
    end

    loop Program Page
        Host->>Target: Program page (0x7)
        Target-->>Host: Acknowledge
    end

    Host->>Target: Exit vendor scope (0x3)
    Target-->>Host: Acknowledge