transport.h (4227B)
1 // Copyright 2023, Brian Swetland <swetland@frotz.net> 2 // Licensed under the Apache License, Version 2.0. 3 4 #pragma once 5 6 #include <stdint.h> 7 8 9 void dc_require_vid_pid(unsigned vid, unsigned pid); 10 void dc_require_serialno(const char* sn); 11 12 typedef struct debug_context dctx_t; 13 int dc_periodic(dctx_t* dc); 14 15 void dc_interrupt(dctx_t* dc); 16 17 uint32_t dc_flags(dctx_t* dc, uint32_t clr, uint32_t set); 18 19 #define DCF_POLL 0x00000001 // query state while attached 20 #define DCF_AUTO_ATTACH 0x00000002 // attach on new command if detached 21 #define DCF_AUTO_CONFIG 0x00000004 // configure some flags based on IDCODE 22 23 #define DC_OK 0 24 #define DC_ERR_FAILED -1 // generic internal failure 25 #define DC_ERR_BAD_PARAMS -2 // Invalid parameters 26 #define DC_ERR_IO -3 // IO error (USB read fail, etc) 27 #define DC_ERR_OFFLINE -4 // IO error (USB device offline) 28 #define DC_ERR_PROTOCOL -5 // Protocol error (bug in sw or fw) 29 #define DC_ERR_TIMEOUT -6 // WAIT response from DP (retries insufficient) 30 #define DC_ERR_SWD_FAULT -7 // FAULT response from DP 31 #define DC_ERR_SWD_PARITY -8 // Corrupt Data 32 #define DC_ERR_SWD_SILENT -9 // No Status Indicated 33 #define DC_ERR_SWD_BOGUS -10 // Nonsensical Status Indicated 34 #define DC_ERR_MATCH -11 // read match failure 35 #define DC_ERR_UNSUPPORTED -12 // unsupported operation 36 #define DC_ERR_REMOTE -13 // failure from debug probe 37 #define DC_ERR_DETACHED -14 // transport not connected to target 38 #define DC_ERR_BAD_STATE -15 39 #define DC_ERR_INTERRUPTED -16 40 41 int dc_set_clock(dctx_t* dc, uint32_t hz); 42 43 // queue Debug Port reads and writes 44 // DP.SELECT will be updated as necessary 45 void dc_q_dp_rd(dctx_t* dc, unsigned dpaddr, uint32_t* val); 46 void dc_q_dp_wr(dctx_t* dc, unsigned dpaddr, uint32_t val); 47 48 // queue Access Port reads and writes 49 // DP.SELECT will be updated as necessary 50 void dc_q_ap_rd(dctx_t* dc, unsigned apaddr, uint32_t* val); 51 void dc_q_ap_wr(dctx_t* dc, unsigned apaddr, uint32_t val); 52 53 // set the max retry count for match operations 54 void dc_set_match_retry(dctx_t* dc, unsigned num); 55 56 // set the mask pattern (in the probe, not the target) 57 void dc_q_set_mask(dctx_t* dc, uint32_t mask); 58 59 // try to read until (readval & mask) == val or timeout 60 void dc_q_ap_match(dctx_t* dc, unsigned apaddr, uint32_t val); 61 void dc_q_dp_match(dctx_t* dc, unsigned apaddr, uint32_t val); 62 63 // prepare for a set of transactions 64 void dc_q_init(dctx_t* dc); 65 66 // execute any outstanding transactions, return final status 67 int dc_q_exec(dctx_t* dc); 68 69 // convenince wrappers for a single read/write and then exec 70 int dc_dp_rd(dctx_t* dc, unsigned dpaddr, uint32_t* val); 71 int dc_dp_wr(dctx_t* dc, unsigned dpaddr, uint32_t val); 72 int dc_ap_rd(dctx_t* dc, unsigned apaddr, uint32_t* val); 73 int dc_ap_wr(dctx_t* dc, unsigned apaddr, uint32_t val); 74 75 // create debug connection 76 int dc_create(dctx_t** dc, void (*cb)(void *cookie, uint32_t status), void *cookie); 77 78 // status values 79 #define DC_ATTACHED 0 // attached and ready to do txns 80 #define DC_FAILURE 1 // last txn failed, need to re-attach 81 #define DC_DETACHED 2 // have not yet attached 82 #define DC_UNCONFIG 3 // configure failed 83 #define DC_OFFLINE 4 // usb connection not available 84 85 // attempt to attach to the debug target 86 int dc_attach(dctx_t* dc, unsigned flags, uint32_t tgt, uint32_t* idcode); 87 #define DC_MULTIDROP 1 88 89 90 void dc_q_mem_rd32(dctx_t* dc, uint32_t addr, uint32_t* val); 91 void dc_q_mem_wr32(dctx_t* dc, uint32_t addr, uint32_t val); 92 void dc_q_mem_match32(dctx_t* dc, uint32_t addr, uint32_t val); 93 94 int dc_mem_rd32(dctx_t* dc, uint32_t addr, uint32_t* val); 95 int dc_mem_wr32(dctx_t* dc, uint32_t addr, uint32_t val); 96 97 int dc_mem_rd_words(dctx_t* dc, uint32_t addr, uint32_t num, uint32_t* ptr); 98 int dc_mem_wr_words(dctx_t* dc, uint32_t addr, uint32_t num, const uint32_t* ptr); 99 100 101 102 int dc_core_halt(dctx_t* dc); 103 int dc_core_resume(dctx_t* dc); 104 int dc_core_step(dctx_t* dc); 105 int dc_core_wait_halt(dctx_t* dc); 106 107 int dc_core_reg_rd(dctx_t* dc, unsigned id, uint32_t* val); 108 int dc_core_reg_wr(dctx_t* dc, unsigned id, uint32_t val); 109 110 int dc_core_reg_rd_list(dctx_t* dc, uint32_t* id, uint32_t* val, unsigned count); 111 112 // 0 = no, 1 = yes, < 0 = error 113 int dc_core_check_halt(dctx_t* dc); 114