pico-mdebug

mdebug firmware for pico / rp2040
git clone http://frotz.net/git/pico-mdebug.git
Log | Files | Refs | README

rswdp.h (4557B)


      1 // Copyright 2011-2021, Brian Swetland <swetland@frotz.net>
      2 // Licensed under the Apache License, Version 2.0.
      3 
      4 /* Remote Serial Wire Debug Protocol */
      5 
      6 #ifndef _RSWDP_PROTOCOL_H_
      7 #define _RSWDP_PROTOCOL_H_
      8 
      9 /* Basic framing:
     10  * - host and device exchange "transactions" consisting of
     11  *   some number of "messages".
     12  * - each "message" has a 32bit header and may have 0 or more
     13  *   32bit words of payload
     14  * - a transaction may not exceed 4K (1024 words)
     15  * - a transaction is sent in a series of USB BULK packets
     16  * - the final packet must be a short packet unless the
     17  *   transaction is exactly 4K in length
     18  * - packets must be a multiple of 4 bytes
     19  * - the first message in a transaction must be
     20  *   CMD_TXN_START or CMD_TXN_ASYNC
     21  */
     22 
     23 #define RSWD_MSG(cmd,op,n)  ((((cmd)&0xFF) << 24) | (((op) & 0xFF)<<16) | ((n) & 0xFFFF))
     24 #define RSWD_MSG_CMD(n)     (((n) >> 24) & 0xFF)
     25 #define RSWD_MSG_OP(n)      (((n) >> 16) & 0xFF)
     26 #define RSWD_MSG_ARG(n)     ((n) & 0xFFFF)
     27 
     28 #define RSWD_TXN_START(seq) (0xAA770000 | ((seq) & 0xFFFF))
     29 #define RSWD_TXN_ASYNC      (0xAA001111)
     30 
     31 /* valid: either */
     32 #define CMD_NULL        0x00 /* used for padding */
     33 
     34 /* valid: host to target */
     35 #define CMD_SWD_WRITE   0x01 /* op=addr arg=count payload: data x count */
     36 #define CMD_SWD_READ    0x02 /* op=addr arg=count payload: data x count */
     37 #define CMD_SWD_DISCARD 0x03 /* op=addr arg=count payload: none (discards) */
     38 #define CMD_ATTACH      0x04 /* do swdp reset/connect handshake */
     39 #define CMD_RESET       0x05 /* arg=1 -> assert RESETn, otherwise deassert */
     40 #define CMD_DOWNLOAD    0x06 /* arg=wordcount, payload: addr x 1, data x n */
     41 #define CMD_EXECUTE     0x07 /* payload: addr x 1 */
     42 #define CMD_TRACE       0x08 /* op=tracebits n=0 */
     43 #define CMD_BOOTLOADER  0x09 /* return to bootloader for reflashing */
     44 #define CMD_SET_CLOCK   0x0A /* set SWCLK rate to n khz */
     45 #define CMD_SWO_CLOCK   0x0B /* set SWOCLK rate to n khz, 0 = disable SWO */
     46 #define CMD_JTAG_IO     0x0C /* op=0, arg=bitcount, data x (count/32) * 2 */
     47 /* tms, tdi word pairs per 32bits */
     48 #define CMD_JTAG_TX     0x0D /* tms=op.0, arg=bitcount, data x (count/32) words of tdi */
     49 #define CMD_JTAG_RX     0x0E /* tms=op.0, tdi=op.1, arg=bitcount, return (count/32) words */
     50 #define CMD_JTAG_VRFY   0x0F /* arg=bitcount, tms/tdi data/mask, error if tdo&mask != data */
     51 
     52 /* ATTACH ops */
     53 #define ATTACH_SWD_RESET 0
     54 #define ATTACH_JTAG_TO_SWD 1
     55 #define ATTACH_DORMANT_TO_SWD 2
     56 #define ATTACH_SWD_TO_DORMANT 3
     57 
     58 /* valid: target to host */
     59 #define CMD_STATUS      0x10 /* op=errorcode, arg=commands since last TXN_START */
     60 #define CMD_SWD_DATA    0x11 /* op=0 arg=count, payload: data x count */
     61 #define CMD_SWO_DATA    0x12 /* op=0 arg=count, payload: ((count+3)/4) words */
     62 #define CMD_JTAG_DATA   0x14 /* op=0 arg=bitcount, payload: (arg/32) words */
     63 
     64 /* valid: target to host async */
     65 #define CMD_DEBUG_PRINT 0x20 /* arg*4 bytes of ascii debug output */
     66 
     67 /* valid: bidirectional query/config messages */
     68 #define CMD_VERSION     0x30 /* arg=bcdversion (0x0100 etc) */
     69 #define CMD_BUILD_STR   0x31 /* arg=wordcount, payload = asciiz */
     70 #define CMD_BOARD_STR   0x32 /* arg=wordcount, payload = asciiz */
     71 #define CMD_RX_MAXDATA  0x33 /* arg=bytes, declares senders rx buffer size */
     72 #define CMD_CLOCK_KHZ   0x34 /* arg=khz, reports active clock rate */
     73 
     74 /* CMD_STATUS error codes */
     75 #define ERR_NONE        0
     76 #define ERR_INTERNAL    1
     77 #define ERR_TIMEOUT     2
     78 #define ERR_IO          3
     79 #define ERR_PARITY      4
     80 #define ERR_BAD_MATCH   5
     81 
     82 
     83 #define RSWD_VERSION_1_0    0x0100
     84 #define RSWD_VERSION_1_1    0x0101
     85 #define RSWD_VERSION_1_2    0x0102
     86 #define RSWD_VERSION_1_3    0x0103
     87 
     88 #define RSWD_VERSION        RSWD_VERSION_1_3
     89 
     90 // Pre-1.0
     91 //  - max packet size fixed at 2048 bytes
     92 //
     93 // Version 1.0
     94 // - CMD_VERSION, CMD_BUILD_STR, CMD_BOARD_STR, CMD_RX_MAXDATA,
     95 //   CMD_CLOCK_KHZ added
     96 //
     97 // Version 1.1
     98 // - CMD_SWO_DATA arg is now byte count, not word count
     99 //
    100 // Version 1.2
    101 // - CMD_JTAG_IO, CMD_JTAG_RX, CMD_JTAG_TX, CMD_JTAG_VRFY, CMD_JTAG_DATA added
    102 //
    103 // Version 1.3
    104 // - CMD_ATTACH ops (ATTACH_xyz), CMD_CLOCK_KHZ op indicates 0=SWCLK, 1=SWO
    105 
    106 /* CMD_SWD_OP operations - combine for direct AP/DP io */
    107 #define OP_RD 0x00
    108 #define OP_WR 0x01
    109 #define OP_DP 0x00
    110 #define OP_AP 0x02
    111 #define OP_X0 0x00
    112 #define OP_X4 0x04
    113 #define OP_X8 0x08
    114 #define OP_XC 0x0C
    115 
    116 /* DP registers */
    117 #define DP_IDCODE   (OP_DP|OP_X0)
    118 #define DP_ABORT    (OP_DP|OP_X0)
    119 #define DP_DPCTRL   (OP_DP|OP_X4)
    120 #define DP_RESEND   (OP_DP|OP_X8)
    121 #define DP_SELECT   (OP_DP|OP_X8)
    122 #define DP_BUFFER   (OP_DP|OP_XC)
    123 
    124 #endif