1 /***************************************************************************
2 * Copyright (C) 2011-2012 by Mathias Kuester *
3 * Mathias Kuester <kesmtp@freenet.de> *
5 * Copyright (C) 2012 by Spencer Oliver *
6 * spen@spen-soft.co.uk *
8 * This code is based on https://github.com/texane/stlink *
10 * This program is free software; you can redistribute it and/or modify *
11 * it under the terms of the GNU General Public License as published by *
12 * the Free Software Foundation; either version 2 of the License, or *
13 * (at your option) any later version. *
15 * This program is distributed in the hope that it will be useful, *
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
18 * GNU General Public License for more details. *
20 * You should have received a copy of the GNU General Public License *
21 * along with this program; if not, write to the *
22 * Free Software Foundation, Inc., *
23 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. *
24 ***************************************************************************/
30 /* project specific includes */
31 #include <helper/binarybuffer.h>
32 #include <jtag/interface.h>
33 #include <jtag/hla/hla_layout.h>
34 #include <jtag/hla/hla_transport.h>
35 #include <jtag/hla/hla_interface.h>
36 #include <target/target.h>
38 #include <target/cortex_m.h>
40 #include "libusb_common.h"
42 #define ENDPOINT_IN 0x80
43 #define ENDPOINT_OUT 0x00
45 #define STLINK_NULL_EP 0
46 #define STLINK_RX_EP (1|ENDPOINT_IN)
47 #define STLINK_TX_EP (2|ENDPOINT_OUT)
48 #define STLINK_TRACE_EP (3|ENDPOINT_IN)
49 #define STLINK_SG_SIZE (31)
50 #define STLINK_DATA_SIZE (4*128)
51 #define STLINK_CMD_SIZE_V2 (16)
52 #define STLINK_CMD_SIZE_V1 (10)
54 enum stlink_jtag_api_version {
55 STLINK_JTAG_API_V1 = 1,
60 struct stlink_usb_version {
67 /** highest supported jtag api version */
68 enum stlink_jtag_api_version jtag_api_max;
72 struct stlink_usb_handle_s {
74 struct jtag_libusb_device_handle *fd;
76 struct libusb_transfer *trans;
78 uint8_t cmdbuf[STLINK_SG_SIZE];
84 uint8_t databuf[STLINK_DATA_SIZE];
86 enum hl_transports transport;
88 struct stlink_usb_version version;
93 /** this is the currently used jtag api */
94 enum stlink_jtag_api_version jtag_api;
97 /** whether SWO tracing is enabled or not */
99 /** trace data destination file */
101 /** trace module source clock (for prescaler) */
103 /** trace module clock prescaler */
108 #define STLINK_DEBUG_ERR_OK 0x80
109 #define STLINK_DEBUG_ERR_FAULT 0x81
110 #define STLINK_SWD_AP_WAIT 0x10
111 #define STLINK_SWD_DP_WAIT 0x14
113 #define STLINK_CORE_RUNNING 0x80
114 #define STLINK_CORE_HALTED 0x81
115 #define STLINK_CORE_STAT_UNKNOWN -1
117 #define STLINK_GET_VERSION 0xF1
118 #define STLINK_DEBUG_COMMAND 0xF2
119 #define STLINK_DFU_COMMAND 0xF3
120 #define STLINK_SWIM_COMMAND 0xF4
121 #define STLINK_GET_CURRENT_MODE 0xF5
122 #define STLINK_GET_TARGET_VOLTAGE 0xF7
124 #define STLINK_DEV_DFU_MODE 0x00
125 #define STLINK_DEV_MASS_MODE 0x01
126 #define STLINK_DEV_DEBUG_MODE 0x02
127 #define STLINK_DEV_SWIM_MODE 0x03
128 #define STLINK_DEV_BOOTLOADER_MODE 0x04
129 #define STLINK_DEV_UNKNOWN_MODE -1
131 #define STLINK_DFU_EXIT 0x07
133 #define STLINK_SWIM_ENTER 0x00
134 #define STLINK_SWIM_EXIT 0x01
136 #define STLINK_DEBUG_ENTER_JTAG 0x00
137 #define STLINK_DEBUG_GETSTATUS 0x01
138 #define STLINK_DEBUG_FORCEDEBUG 0x02
139 #define STLINK_DEBUG_APIV1_RESETSYS 0x03
140 #define STLINK_DEBUG_APIV1_READALLREGS 0x04
141 #define STLINK_DEBUG_APIV1_READREG 0x05
142 #define STLINK_DEBUG_APIV1_WRITEREG 0x06
143 #define STLINK_DEBUG_READMEM_32BIT 0x07
144 #define STLINK_DEBUG_WRITEMEM_32BIT 0x08
145 #define STLINK_DEBUG_RUNCORE 0x09
146 #define STLINK_DEBUG_STEPCORE 0x0a
147 #define STLINK_DEBUG_APIV1_SETFP 0x0b
148 #define STLINK_DEBUG_READMEM_8BIT 0x0c
149 #define STLINK_DEBUG_WRITEMEM_8BIT 0x0d
150 #define STLINK_DEBUG_APIV1_CLEARFP 0x0e
151 #define STLINK_DEBUG_APIV1_WRITEDEBUGREG 0x0f
152 #define STLINK_DEBUG_APIV1_SETWATCHPOINT 0x10
154 #define STLINK_DEBUG_ENTER_JTAG 0x00
155 #define STLINK_DEBUG_ENTER_SWD 0xa3
157 #define STLINK_DEBUG_APIV1_ENTER 0x20
158 #define STLINK_DEBUG_EXIT 0x21
159 #define STLINK_DEBUG_READCOREID 0x22
161 #define STLINK_DEBUG_APIV2_ENTER 0x30
162 #define STLINK_DEBUG_APIV2_READ_IDCODES 0x31
163 #define STLINK_DEBUG_APIV2_RESETSYS 0x32
164 #define STLINK_DEBUG_APIV2_READREG 0x33
165 #define STLINK_DEBUG_APIV2_WRITEREG 0x34
166 #define STLINK_DEBUG_APIV2_WRITEDEBUGREG 0x35
167 #define STLINK_DEBUG_APIV2_READDEBUGREG 0x36
169 #define STLINK_DEBUG_APIV2_READALLREGS 0x3A
170 #define STLINK_DEBUG_APIV2_GETLASTRWSTATUS 0x3B
171 #define STLINK_DEBUG_APIV2_DRIVE_NRST 0x3C
173 #define STLINK_DEBUG_APIV2_START_TRACE_RX 0x40
174 #define STLINK_DEBUG_APIV2_STOP_TRACE_RX 0x41
175 #define STLINK_DEBUG_APIV2_GET_TRACE_NB 0x42
177 #define STLINK_DEBUG_APIV2_DRIVE_NRST_LOW 0x00
178 #define STLINK_DEBUG_APIV2_DRIVE_NRST_HIGH 0x01
179 #define STLINK_DEBUG_APIV2_DRIVE_NRST_PULSE 0x02
181 #define STLINK_TRACE_SIZE 1024
182 #define STLINK_TRACE_MAX_HZ 2000000
183 #define STLINK_TRACE_MIN_VERSION 13
187 STLINK_MODE_UNKNOWN = 0,
190 STLINK_MODE_DEBUG_JTAG,
191 STLINK_MODE_DEBUG_SWD,
192 STLINK_MODE_DEBUG_SWIM
195 #define REQUEST_SENSE 0x03
196 #define REQUEST_SENSE_LENGTH 18
198 static void stlink_usb_init_buffer(void *handle, uint8_t direction, uint32_t size);
201 static int stlink_usb_xfer_v1_get_status(void *handle)
203 struct stlink_usb_handle_s *h;
205 assert(handle != NULL);
207 h = (struct stlink_usb_handle_s *)handle;
210 memset(h->cmdbuf, 0, STLINK_SG_SIZE);
212 if (jtag_libusb_bulk_read(h->fd, STLINK_RX_EP, (char *)h->cmdbuf,
218 t1 = buf_get_u32(h->cmdbuf, 0, 32);
221 if (t1 != 0x53425355)
229 if (h->cmdbuf[12] != 0)
236 static int stlink_usb_xfer_rw(void *handle, int cmdsize, const uint8_t *buf, int size)
238 struct stlink_usb_handle_s *h;
240 assert(handle != NULL);
242 h = (struct stlink_usb_handle_s *)handle;
244 if (jtag_libusb_bulk_write(h->fd, STLINK_TX_EP, (char *)h->cmdbuf, cmdsize,
249 if (h->direction == STLINK_TX_EP && size) {
250 if (jtag_libusb_bulk_write(h->fd, STLINK_TX_EP, (char *)buf,
251 size, 1000) != size) {
252 LOG_DEBUG("bulk write failed");
255 } else if (h->direction == STLINK_RX_EP && size) {
256 if (jtag_libusb_bulk_read(h->fd, STLINK_RX_EP, (char *)buf,
257 size, 1000) != size) {
258 LOG_DEBUG("bulk read failed");
267 static int stlink_usb_xfer_v1_get_sense(void *handle)
270 struct stlink_usb_handle_s *h;
272 assert(handle != NULL);
274 h = (struct stlink_usb_handle_s *)handle;
276 stlink_usb_init_buffer(handle, STLINK_RX_EP, 16);
278 h->cmdbuf[h->cmdidx++] = REQUEST_SENSE;
279 h->cmdbuf[h->cmdidx++] = 0;
280 h->cmdbuf[h->cmdidx++] = 0;
281 h->cmdbuf[h->cmdidx++] = 0;
282 h->cmdbuf[h->cmdidx++] = REQUEST_SENSE_LENGTH;
284 res = stlink_usb_xfer_rw(handle, REQUEST_SENSE_LENGTH, h->databuf, 16);
289 if (stlink_usb_xfer_v1_get_status(handle) != ERROR_OK)
296 static int stlink_usb_xfer(void *handle, const uint8_t *buf, int size)
298 int err, cmdsize = STLINK_CMD_SIZE_V2;
299 struct stlink_usb_handle_s *h;
301 assert(handle != NULL);
303 h = (struct stlink_usb_handle_s *)handle;
305 if (h->version.stlink == 1)
306 cmdsize = STLINK_SG_SIZE;
308 err = stlink_usb_xfer_rw(handle, cmdsize, buf, size);
313 if (h->version.stlink == 1) {
314 if (stlink_usb_xfer_v1_get_status(handle) != ERROR_OK) {
315 /* check csw status */
316 if (h->cmdbuf[12] == 1) {
317 LOG_DEBUG("get sense");
318 if (stlink_usb_xfer_v1_get_sense(handle) != ERROR_OK)
329 static int stlink_usb_read_trace(void *handle, const uint8_t *buf, int size)
331 struct stlink_usb_handle_s *h;
333 assert(handle != NULL);
335 h = (struct stlink_usb_handle_s *)handle;
337 assert(h->version.stlink >= 2);
339 if (jtag_libusb_bulk_read(h->fd, STLINK_TRACE_EP, (char *)buf,
340 size, 1000) != size) {
341 LOG_ERROR("bulk trace read failed");
349 static void stlink_usb_xfer_v1_create_cmd(void *handle, uint8_t direction, uint32_t size)
351 struct stlink_usb_handle_s *h;
353 h = (struct stlink_usb_handle_s *)handle;
355 /* fill the send buffer */
356 strcpy((char *)h->cmdbuf, "USBC");
358 /* csw tag not used */
360 buf_set_u32(h->cmdbuf+h->cmdidx, 0, 32, size);
362 h->cmdbuf[h->cmdidx++] = (direction == STLINK_RX_EP ? ENDPOINT_IN : ENDPOINT_OUT);
363 h->cmdbuf[h->cmdidx++] = 0; /* lun */
364 h->cmdbuf[h->cmdidx++] = STLINK_CMD_SIZE_V1;
368 static void stlink_usb_init_buffer(void *handle, uint8_t direction, uint32_t size)
370 struct stlink_usb_handle_s *h;
372 h = (struct stlink_usb_handle_s *)handle;
374 h->direction = direction;
378 memset(h->cmdbuf, 0, STLINK_SG_SIZE);
379 memset(h->databuf, 0, STLINK_DATA_SIZE);
381 if (h->version.stlink == 1)
382 stlink_usb_xfer_v1_create_cmd(handle, direction, size);
385 static const char * const stlink_usb_error_msg[] = {
390 static int stlink_usb_error_check(void *handle)
393 const char *err_msg = 0;
394 struct stlink_usb_handle_s *h;
396 assert(handle != NULL);
398 h = (struct stlink_usb_handle_s *)handle;
400 /* TODO: no error checking yet on api V1 */
401 if (h->jtag_api == STLINK_JTAG_API_V1)
402 h->databuf[0] = STLINK_DEBUG_ERR_OK;
404 switch (h->databuf[0]) {
405 case STLINK_DEBUG_ERR_OK:
408 case STLINK_DEBUG_ERR_FAULT:
410 err_msg = stlink_usb_error_msg[0];
416 LOG_DEBUG("status error: %d ('%s')", h->databuf[0], err_msg);
422 static int stlink_usb_version(void *handle)
426 struct stlink_usb_handle_s *h;
428 assert(handle != NULL);
430 h = (struct stlink_usb_handle_s *)handle;
432 stlink_usb_init_buffer(handle, STLINK_RX_EP, 6);
434 h->cmdbuf[h->cmdidx++] = STLINK_GET_VERSION;
436 res = stlink_usb_xfer(handle, h->databuf, 6);
441 v = (h->databuf[0] << 8) | h->databuf[1];
443 h->version.stlink = (v >> 12) & 0x0f;
444 h->version.jtag = (v >> 6) & 0x3f;
445 h->version.swim = v & 0x3f;
446 h->vid = buf_get_u32(h->databuf, 16, 16);
447 h->pid = buf_get_u32(h->databuf, 32, 16);
449 /* set the supported jtag api version
450 * API V2 is supported since JTAG V11
452 if (h->version.jtag >= 11)
453 h->version.jtag_api_max = STLINK_JTAG_API_V2;
455 h->version.jtag_api_max = STLINK_JTAG_API_V1;
457 LOG_INFO("STLINK v%d JTAG v%d API v%d SWIM v%d VID 0x%04X PID 0x%04X",
460 (h->version.jtag_api_max == STLINK_JTAG_API_V1) ? 1 : 2,
468 static int stlink_usb_check_voltage(void *handle, float *target_voltage)
470 struct stlink_usb_handle_s *h;
471 uint32_t adc_results[2];
473 h = (struct stlink_usb_handle_s *)handle;
475 /* only supported by stlink/v2 and for firmware >= 13 */
476 if (h->version.stlink == 1 || h->version.jtag < 13)
477 return ERROR_COMMAND_NOTFOUND;
479 stlink_usb_init_buffer(handle, STLINK_RX_EP, 8);
481 h->cmdbuf[h->cmdidx++] = STLINK_GET_TARGET_VOLTAGE;
483 int result = stlink_usb_xfer(handle, h->databuf, 8);
485 if (result != ERROR_OK)
489 adc_results[0] = le_to_h_u32(h->databuf);
490 adc_results[1] = le_to_h_u32(h->databuf + 4);
495 *target_voltage = 2 * ((float)adc_results[1]) * (float)(1.2 / adc_results[0]);
497 LOG_INFO("Target voltage: %f", (double)*target_voltage);
503 static int stlink_usb_current_mode(void *handle, uint8_t *mode)
506 struct stlink_usb_handle_s *h;
508 assert(handle != NULL);
510 h = (struct stlink_usb_handle_s *)handle;
512 stlink_usb_init_buffer(handle, STLINK_RX_EP, 2);
514 h->cmdbuf[h->cmdidx++] = STLINK_GET_CURRENT_MODE;
516 res = stlink_usb_xfer(handle, h->databuf, 2);
521 *mode = h->databuf[0];
527 static int stlink_usb_mode_enter(void *handle, enum stlink_mode type)
531 struct stlink_usb_handle_s *h;
533 assert(handle != NULL);
535 h = (struct stlink_usb_handle_s *)handle;
537 /* on api V2 we are able the read the latest command
539 * TODO: we need the test on api V1 too
541 if (h->jtag_api == STLINK_JTAG_API_V2)
544 stlink_usb_init_buffer(handle, STLINK_RX_EP, rx_size);
547 case STLINK_MODE_DEBUG_JTAG:
548 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
549 if (h->jtag_api == STLINK_JTAG_API_V1)
550 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV1_ENTER;
552 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV2_ENTER;
553 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_ENTER_JTAG;
555 case STLINK_MODE_DEBUG_SWD:
556 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
557 if (h->jtag_api == STLINK_JTAG_API_V1)
558 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV1_ENTER;
560 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV2_ENTER;
561 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_ENTER_SWD;
563 case STLINK_MODE_DEBUG_SWIM:
564 h->cmdbuf[h->cmdidx++] = STLINK_SWIM_COMMAND;
565 h->cmdbuf[h->cmdidx++] = STLINK_SWIM_ENTER;
567 case STLINK_MODE_DFU:
568 case STLINK_MODE_MASS:
573 res = stlink_usb_xfer(handle, h->databuf, rx_size);
578 res = stlink_usb_error_check(h);
584 static int stlink_usb_mode_leave(void *handle, enum stlink_mode type)
587 struct stlink_usb_handle_s *h;
589 assert(handle != NULL);
591 h = (struct stlink_usb_handle_s *)handle;
593 stlink_usb_init_buffer(handle, STLINK_NULL_EP, 0);
596 case STLINK_MODE_DEBUG_JTAG:
597 case STLINK_MODE_DEBUG_SWD:
598 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
599 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_EXIT;
601 case STLINK_MODE_DEBUG_SWIM:
602 h->cmdbuf[h->cmdidx++] = STLINK_SWIM_COMMAND;
603 h->cmdbuf[h->cmdidx++] = STLINK_SWIM_EXIT;
605 case STLINK_MODE_DFU:
606 h->cmdbuf[h->cmdidx++] = STLINK_DFU_COMMAND;
607 h->cmdbuf[h->cmdidx++] = STLINK_DFU_EXIT;
609 case STLINK_MODE_MASS:
614 res = stlink_usb_xfer(handle, 0, 0);
622 static int stlink_usb_assert_srst(void *handle, int srst);
625 static int stlink_usb_init_mode(void *handle, bool connect_under_reset)
629 enum stlink_mode emode;
630 struct stlink_usb_handle_s *h;
632 assert(handle != NULL);
634 h = (struct stlink_usb_handle_s *)handle;
636 res = stlink_usb_current_mode(handle, &mode);
641 LOG_DEBUG("MODE: 0x%02X", mode);
643 /* try to exit current mode */
645 case STLINK_DEV_DFU_MODE:
646 emode = STLINK_MODE_DFU;
648 case STLINK_DEV_DEBUG_MODE:
649 emode = STLINK_MODE_DEBUG_SWD;
651 case STLINK_DEV_SWIM_MODE:
652 emode = STLINK_MODE_DEBUG_SWIM;
654 case STLINK_DEV_BOOTLOADER_MODE:
655 case STLINK_DEV_MASS_MODE:
657 emode = STLINK_MODE_UNKNOWN;
661 if (emode != STLINK_MODE_UNKNOWN) {
662 res = stlink_usb_mode_leave(handle, emode);
668 res = stlink_usb_current_mode(handle, &mode);
673 /* we check the target voltage here as an aid to debugging connection problems.
674 * the stlink requires the target Vdd to be connected for reliable debugging.
675 * this cmd is supported in all modes except DFU
677 if (mode != STLINK_DEV_DFU_MODE) {
679 float target_voltage;
681 /* check target voltage (if supported) */
682 res = stlink_usb_check_voltage(h, &target_voltage);
684 if (res != ERROR_OK) {
685 if (res != ERROR_COMMAND_NOTFOUND)
686 LOG_ERROR("voltage check failed");
687 /* attempt to continue as it is not a catastrophic failure */
689 /* check for a sensible target voltage, operating range is 1.65-5.5v
690 * according to datasheet */
691 if (target_voltage < 1.5)
692 LOG_ERROR("target voltage may be too low for reliable debugging");
696 LOG_DEBUG("MODE: 0x%02X", mode);
698 /* set selected mode */
699 switch (h->transport) {
700 case HL_TRANSPORT_SWD:
701 emode = STLINK_MODE_DEBUG_SWD;
703 case HL_TRANSPORT_JTAG:
704 emode = STLINK_MODE_DEBUG_JTAG;
706 case HL_TRANSPORT_SWIM:
707 emode = STLINK_MODE_DEBUG_SWIM;
710 emode = STLINK_MODE_UNKNOWN;
714 if (emode == STLINK_MODE_UNKNOWN) {
715 LOG_ERROR("selected mode (transport) not supported");
719 if (connect_under_reset) {
720 res = stlink_usb_assert_srst(handle, 0);
725 res = stlink_usb_mode_enter(handle, emode);
730 res = stlink_usb_current_mode(handle, &mode);
735 LOG_DEBUG("MODE: 0x%02X", mode);
741 static int stlink_usb_idcode(void *handle, uint32_t *idcode)
744 struct stlink_usb_handle_s *h;
746 assert(handle != NULL);
748 h = (struct stlink_usb_handle_s *)handle;
750 stlink_usb_init_buffer(handle, STLINK_RX_EP, 4);
752 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
753 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_READCOREID;
755 res = stlink_usb_xfer(handle, h->databuf, 4);
760 *idcode = le_to_h_u32(h->databuf);
762 LOG_DEBUG("IDCODE: 0x%08X", *idcode);
767 static int stlink_usb_v2_read_debug_reg(void *handle, uint32_t addr, uint32_t *val)
769 struct stlink_usb_handle_s *h;
772 assert(handle != NULL);
774 h = (struct stlink_usb_handle_s *)handle;
776 stlink_usb_init_buffer(handle, STLINK_RX_EP, 8);
778 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
779 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV2_READDEBUGREG;
780 h_u32_to_le(h->cmdbuf+h->cmdidx, addr);
783 res = stlink_usb_xfer(handle, h->databuf, 8);
788 *val = le_to_h_u32(h->databuf + 4);
790 return h->databuf[0] == STLINK_DEBUG_ERR_OK ? ERROR_OK : ERROR_FAIL;
793 static int stlink_usb_write_debug_reg(void *handle, uint32_t addr, uint32_t val)
796 struct stlink_usb_handle_s *h;
798 assert(handle != NULL);
800 h = (struct stlink_usb_handle_s *)handle;
802 stlink_usb_init_buffer(handle, STLINK_RX_EP, 2);
804 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
805 if (h->jtag_api == STLINK_JTAG_API_V1)
806 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV1_WRITEDEBUGREG;
808 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV2_WRITEDEBUGREG;
809 h_u32_to_le(h->cmdbuf+h->cmdidx, addr);
811 h_u32_to_le(h->cmdbuf+h->cmdidx, val);
814 res = stlink_usb_xfer(handle, h->databuf, 2);
819 return h->databuf[0] == STLINK_DEBUG_ERR_OK ? ERROR_OK : ERROR_FAIL;
823 static void stlink_usb_trace_read(void *handle)
825 struct stlink_usb_handle_s *h;
827 assert(handle != NULL);
829 h = (struct stlink_usb_handle_s *)handle;
831 if (h->trace.enabled && h->version.jtag >= STLINK_TRACE_MIN_VERSION) {
834 stlink_usb_init_buffer(handle, STLINK_RX_EP, 10);
836 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
837 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV2_GET_TRACE_NB;
839 res = stlink_usb_xfer(handle, h->databuf, 2);
840 if (res == ERROR_OK) {
841 uint8_t buf[STLINK_TRACE_SIZE];
842 size_t size = le_to_h_u16(h->databuf);
845 size = size < sizeof(buf) ? size : sizeof(buf) - 1;
847 res = stlink_usb_read_trace(handle, buf, size);
848 if (res == ERROR_OK) {
849 /* Log retrieved trace output */
850 if (fwrite(buf, 1, size, h->trace.output_f) > 0)
851 fflush(h->trace.output_f);
858 static enum target_state stlink_usb_v2_get_status(void *handle)
863 result = stlink_usb_v2_read_debug_reg(handle, DCB_DHCSR, &status);
864 if (result != ERROR_OK)
865 return TARGET_UNKNOWN;
868 return TARGET_HALTED;
869 else if (status & S_RESET_ST)
872 stlink_usb_trace_read(handle);
874 return TARGET_RUNNING;
878 static enum target_state stlink_usb_state(void *handle)
881 struct stlink_usb_handle_s *h;
883 assert(handle != NULL);
885 h = (struct stlink_usb_handle_s *)handle;
887 if (h->jtag_api == STLINK_JTAG_API_V2)
888 return stlink_usb_v2_get_status(handle);
890 stlink_usb_init_buffer(handle, STLINK_RX_EP, 2);
892 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
893 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_GETSTATUS;
895 res = stlink_usb_xfer(handle, h->databuf, 2);
898 return TARGET_UNKNOWN;
900 if (h->databuf[0] == STLINK_CORE_RUNNING)
901 return TARGET_RUNNING;
902 if (h->databuf[0] == STLINK_CORE_HALTED)
903 return TARGET_HALTED;
905 return TARGET_UNKNOWN;
909 static int stlink_usb_reset(void *handle)
912 struct stlink_usb_handle_s *h;
914 assert(handle != NULL);
916 h = (struct stlink_usb_handle_s *)handle;
918 stlink_usb_init_buffer(handle, STLINK_RX_EP, 2);
920 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
922 if (h->jtag_api == STLINK_JTAG_API_V1)
923 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV1_RESETSYS;
925 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV2_RESETSYS;
927 res = stlink_usb_xfer(handle, h->databuf, 2);
932 LOG_DEBUG("RESET: 0x%08X", h->databuf[0]);
934 /* the following is not a error under swd (using hardware srst), so return success */
935 if (h->databuf[0] == STLINK_SWD_AP_WAIT || h->databuf[0] == STLINK_SWD_DP_WAIT)
938 return h->databuf[0] == STLINK_DEBUG_ERR_OK ? ERROR_OK : ERROR_FAIL;
941 static int stlink_usb_assert_srst(void *handle, int srst)
944 struct stlink_usb_handle_s *h;
946 assert(handle != NULL);
948 h = (struct stlink_usb_handle_s *)handle;
950 if (h->jtag_api == STLINK_JTAG_API_V1)
951 return ERROR_COMMAND_NOTFOUND;
953 stlink_usb_init_buffer(handle, STLINK_RX_EP, 2);
955 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
956 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV2_DRIVE_NRST;
957 h->cmdbuf[h->cmdidx++] = srst;
959 res = stlink_usb_xfer(handle, h->databuf, 2);
964 return h->databuf[0] == STLINK_DEBUG_ERR_OK ? ERROR_OK : ERROR_FAIL;
968 static int stlink_configure_target_trace_port(void *handle)
972 struct stlink_usb_handle_s *h;
974 assert(handle != NULL);
976 h = (struct stlink_usb_handle_s *)handle;
978 /* configure the TPI */
980 /* enable the trace subsystem */
981 res = stlink_usb_v2_read_debug_reg(handle, DCB_DEMCR, ®);
984 res = stlink_usb_write_debug_reg(handle, DCB_DEMCR, TRCENA|reg);
987 /* set the TPI clock prescaler */
988 res = stlink_usb_write_debug_reg(handle, TPI_ACPR, h->trace.prescale);
991 /* select the pin protocol. The STLinkv2 only supports asynchronous
992 * UART emulation (NRZ) mode, so that's what we pick. */
993 res = stlink_usb_write_debug_reg(handle, TPI_SPPR, 0x02);
996 /* disable continuous formatting */
997 res = stlink_usb_write_debug_reg(handle, TPI_FFCR, (1<<8));
1001 /* configure the ITM */
1003 /* unlock access to the ITM registers */
1004 res = stlink_usb_write_debug_reg(handle, ITM_LAR, 0xC5ACCE55);
1005 if (res != ERROR_OK)
1007 /* enable trace with ATB ID 1 */
1008 res = stlink_usb_write_debug_reg(handle, ITM_TCR, (1<<16)|(1<<0)|(1<<2));
1009 if (res != ERROR_OK)
1011 /* trace privilege */
1012 res = stlink_usb_write_debug_reg(handle, ITM_TPR, 1);
1013 if (res != ERROR_OK)
1015 /* trace port enable (port 0) */
1016 res = stlink_usb_write_debug_reg(handle, ITM_TER, (1<<0));
1017 if (res != ERROR_OK)
1026 static void stlink_usb_trace_disable(void *handle)
1029 struct stlink_usb_handle_s *h;
1031 assert(handle != NULL);
1033 h = (struct stlink_usb_handle_s *)handle;
1035 assert(h->version.jtag >= STLINK_TRACE_MIN_VERSION);
1037 LOG_DEBUG("Tracing: disable\n");
1039 stlink_usb_init_buffer(handle, STLINK_RX_EP, 2);
1040 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
1041 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV2_STOP_TRACE_RX;
1042 res = stlink_usb_xfer(handle, h->databuf, 2);
1044 if (res == ERROR_OK)
1045 h->trace.enabled = false;
1050 static int stlink_usb_trace_enable(void *handle)
1053 struct stlink_usb_handle_s *h;
1055 assert(handle != NULL);
1057 h = (struct stlink_usb_handle_s *)handle;
1059 if (h->version.jtag >= STLINK_TRACE_MIN_VERSION) {
1062 res = stlink_configure_target_trace_port(handle);
1063 if (res != ERROR_OK)
1064 LOG_ERROR("Unable to configure tracing on target\n");
1066 trace_hz = h->trace.prescale > 0 ?
1067 h->trace.source_hz / (h->trace.prescale + 1) :
1070 stlink_usb_init_buffer(handle, STLINK_RX_EP, 10);
1072 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
1073 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV2_START_TRACE_RX;
1074 h_u16_to_le(h->cmdbuf+h->cmdidx, (uint16_t)STLINK_TRACE_SIZE);
1076 h_u32_to_le(h->cmdbuf+h->cmdidx, trace_hz);
1079 res = stlink_usb_xfer(handle, h->databuf, 2);
1081 if (res == ERROR_OK) {
1082 h->trace.enabled = true;
1083 LOG_DEBUG("Tracing: recording at %uHz\n", trace_hz);
1086 LOG_ERROR("Tracing is not supported by this version.");
1094 static int stlink_usb_run(void *handle)
1097 struct stlink_usb_handle_s *h;
1099 assert(handle != NULL);
1101 h = (struct stlink_usb_handle_s *)handle;
1103 if (h->jtag_api == STLINK_JTAG_API_V2) {
1104 res = stlink_usb_write_debug_reg(handle, DCB_DHCSR, DBGKEY|C_DEBUGEN);
1106 /* Try to start tracing, if requested */
1107 if (res == ERROR_OK && h->trace.output_f) {
1108 if (stlink_usb_trace_enable(handle) == ERROR_OK)
1109 LOG_DEBUG("Tracing: enabled\n");
1111 LOG_ERROR("Tracing: enable failed\n");
1117 stlink_usb_init_buffer(handle, STLINK_RX_EP, 2);
1119 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
1120 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_RUNCORE;
1122 res = stlink_usb_xfer(handle, h->databuf, 2);
1124 if (res != ERROR_OK)
1127 return h->databuf[0] == STLINK_DEBUG_ERR_OK ? ERROR_OK : ERROR_FAIL;
1131 static int stlink_usb_halt(void *handle)
1134 struct stlink_usb_handle_s *h;
1136 assert(handle != NULL);
1138 h = (struct stlink_usb_handle_s *)handle;
1140 if (h->jtag_api == STLINK_JTAG_API_V2) {
1141 res = stlink_usb_write_debug_reg(handle, DCB_DHCSR, DBGKEY|C_HALT|C_DEBUGEN);
1143 if (res == ERROR_OK && h->trace.enabled)
1144 stlink_usb_trace_disable(handle);
1149 stlink_usb_init_buffer(handle, STLINK_RX_EP, 2);
1151 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
1152 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_FORCEDEBUG;
1154 res = stlink_usb_xfer(handle, h->databuf, 2);
1156 if (res != ERROR_OK)
1159 return h->databuf[0] == STLINK_DEBUG_ERR_OK ? ERROR_OK : ERROR_FAIL;
1163 static int stlink_usb_step(void *handle)
1166 struct stlink_usb_handle_s *h;
1168 assert(handle != NULL);
1170 h = (struct stlink_usb_handle_s *)handle;
1172 if (h->jtag_api == STLINK_JTAG_API_V2) {
1173 /* TODO: this emulates the v1 api, it should really use a similar auto mask isr
1174 * that the cortex-m3 currently does. */
1175 stlink_usb_write_debug_reg(handle, DCB_DHCSR, DBGKEY|C_HALT|C_MASKINTS|C_DEBUGEN);
1176 stlink_usb_write_debug_reg(handle, DCB_DHCSR, DBGKEY|C_STEP|C_MASKINTS|C_DEBUGEN);
1177 return stlink_usb_write_debug_reg(handle, DCB_DHCSR, DBGKEY|C_HALT|C_DEBUGEN);
1180 stlink_usb_init_buffer(handle, STLINK_RX_EP, 2);
1182 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
1183 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_STEPCORE;
1185 res = stlink_usb_xfer(handle, h->databuf, 2);
1187 if (res != ERROR_OK)
1190 return h->databuf[0] == STLINK_DEBUG_ERR_OK ? ERROR_OK : ERROR_FAIL;
1194 static int stlink_usb_read_regs(void *handle)
1197 struct stlink_usb_handle_s *h;
1199 assert(handle != NULL);
1201 h = (struct stlink_usb_handle_s *)handle;
1203 stlink_usb_init_buffer(handle, STLINK_RX_EP, 84);
1205 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
1206 if (h->jtag_api == STLINK_JTAG_API_V1)
1207 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV1_READALLREGS;
1209 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV2_READALLREGS;
1211 res = stlink_usb_xfer(handle, h->databuf, 84);
1213 if (res != ERROR_OK)
1220 static int stlink_usb_read_reg(void *handle, int num, uint32_t *val)
1223 struct stlink_usb_handle_s *h;
1225 assert(handle != NULL);
1227 h = (struct stlink_usb_handle_s *)handle;
1229 stlink_usb_init_buffer(handle, STLINK_RX_EP, h->jtag_api == STLINK_JTAG_API_V1 ? 4 : 8);
1231 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
1232 if (h->jtag_api == STLINK_JTAG_API_V1)
1233 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV1_READREG;
1235 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV2_READREG;
1236 h->cmdbuf[h->cmdidx++] = num;
1238 res = stlink_usb_xfer(handle, h->databuf, h->jtag_api == STLINK_JTAG_API_V1 ? 4 : 8);
1240 if (res != ERROR_OK)
1243 if (h->jtag_api == STLINK_JTAG_API_V1)
1244 *val = le_to_h_u32(h->databuf);
1246 *val = le_to_h_u32(h->databuf + 4);
1247 return h->databuf[0] == STLINK_DEBUG_ERR_OK ? ERROR_OK : ERROR_FAIL;
1254 static int stlink_usb_write_reg(void *handle, int num, uint32_t val)
1257 struct stlink_usb_handle_s *h;
1259 assert(handle != NULL);
1261 h = (struct stlink_usb_handle_s *)handle;
1263 stlink_usb_init_buffer(handle, STLINK_RX_EP, 2);
1265 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
1266 if (h->jtag_api == STLINK_JTAG_API_V1)
1267 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV1_WRITEREG;
1269 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV2_WRITEREG;
1270 h->cmdbuf[h->cmdidx++] = num;
1271 h_u32_to_le(h->cmdbuf+h->cmdidx, val);
1274 res = stlink_usb_xfer(handle, h->databuf, 2);
1276 if (res != ERROR_OK)
1279 return h->databuf[0] == STLINK_DEBUG_ERR_OK ? ERROR_OK : ERROR_FAIL;
1282 static int stlink_usb_get_rw_status(void *handle)
1285 struct stlink_usb_handle_s *h;
1287 assert(handle != NULL);
1289 h = (struct stlink_usb_handle_s *)handle;
1291 if (h->jtag_api == STLINK_JTAG_API_V1)
1294 stlink_usb_init_buffer(handle, STLINK_RX_EP, 2);
1296 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
1297 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_APIV2_GETLASTRWSTATUS;
1299 res = stlink_usb_xfer(handle, h->databuf, 2);
1301 if (res != ERROR_OK)
1304 return h->databuf[0] == STLINK_DEBUG_ERR_OK ? ERROR_OK : res;
1308 static int stlink_usb_read_mem8(void *handle, uint32_t addr, uint16_t len,
1312 uint16_t read_len = len;
1313 struct stlink_usb_handle_s *h;
1315 assert(handle != NULL);
1317 h = (struct stlink_usb_handle_s *)handle;
1319 stlink_usb_init_buffer(handle, STLINK_RX_EP, read_len);
1321 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
1322 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_READMEM_8BIT;
1323 h_u32_to_le(h->cmdbuf+h->cmdidx, addr);
1325 h_u16_to_le(h->cmdbuf+h->cmdidx, len);
1328 /* we need to fix read length for single bytes */
1332 res = stlink_usb_xfer(handle, h->databuf, read_len);
1334 if (res != ERROR_OK)
1337 memcpy(buffer, h->databuf, len);
1339 return stlink_usb_get_rw_status(handle);
1343 static int stlink_usb_write_mem8(void *handle, uint32_t addr, uint16_t len,
1344 const uint8_t *buffer)
1347 struct stlink_usb_handle_s *h;
1349 assert(handle != NULL);
1351 h = (struct stlink_usb_handle_s *)handle;
1353 stlink_usb_init_buffer(handle, STLINK_TX_EP, len);
1355 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
1356 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_WRITEMEM_8BIT;
1357 h_u32_to_le(h->cmdbuf+h->cmdidx, addr);
1359 h_u16_to_le(h->cmdbuf+h->cmdidx, len);
1362 res = stlink_usb_xfer(handle, buffer, len);
1364 if (res != ERROR_OK)
1367 return stlink_usb_get_rw_status(handle);
1371 static int stlink_usb_read_mem32(void *handle, uint32_t addr, uint16_t len,
1375 struct stlink_usb_handle_s *h;
1377 assert(handle != NULL);
1379 h = (struct stlink_usb_handle_s *)handle;
1383 stlink_usb_init_buffer(handle, STLINK_RX_EP, len);
1385 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
1386 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_READMEM_32BIT;
1387 h_u32_to_le(h->cmdbuf+h->cmdidx, addr);
1389 h_u16_to_le(h->cmdbuf+h->cmdidx, len);
1392 res = stlink_usb_xfer(handle, h->databuf, len);
1394 if (res != ERROR_OK)
1397 memcpy(buffer, h->databuf, len);
1399 return stlink_usb_get_rw_status(handle);
1403 static int stlink_usb_write_mem32(void *handle, uint32_t addr, uint16_t len,
1404 const uint8_t *buffer)
1407 struct stlink_usb_handle_s *h;
1409 assert(handle != NULL);
1411 h = (struct stlink_usb_handle_s *)handle;
1415 stlink_usb_init_buffer(handle, STLINK_TX_EP, len);
1417 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_COMMAND;
1418 h->cmdbuf[h->cmdidx++] = STLINK_DEBUG_WRITEMEM_32BIT;
1419 h_u32_to_le(h->cmdbuf+h->cmdidx, addr);
1421 h_u16_to_le(h->cmdbuf+h->cmdidx, len);
1424 res = stlink_usb_xfer(handle, buffer, len);
1426 if (res != ERROR_OK)
1429 return stlink_usb_get_rw_status(handle);
1433 static int stlink_usb_close(void *fd)
1435 struct stlink_usb_handle_s *h;
1437 h = (struct stlink_usb_handle_s *)fd;
1440 jtag_libusb_close(h->fd);
1448 static int stlink_usb_open(struct hl_interface_param_s *param, void **fd)
1450 int err, retry_count = 1;
1451 struct stlink_usb_handle_s *h;
1452 enum stlink_jtag_api_version api;
1454 LOG_DEBUG("stlink_usb_open");
1456 h = calloc(1, sizeof(struct stlink_usb_handle_s));
1459 LOG_DEBUG("malloc failed");
1463 h->transport = param->transport;
1465 /* set max read/write buffer size in bytes */
1466 param->max_buffer = 512;
1468 const uint16_t vids[] = { param->vid, 0 };
1469 const uint16_t pids[] = { param->pid, 0 };
1471 LOG_DEBUG("transport: %d vid: 0x%04x pid: 0x%04x", param->transport,
1472 param->vid, param->pid);
1475 On certain host USB configurations(e.g. MacBook Air)
1476 STLINKv2 dongle seems to have its FW in a funky state if,
1477 after plugging it in, you try to use openocd with it more
1478 then once (by launching and closing openocd). In cases like
1479 that initial attempt to read the FW info via
1480 stlink_usb_version will fail and the device has to be reset
1481 in order to become operational.
1484 if (jtag_libusb_open(vids, pids, &h->fd) != ERROR_OK) {
1485 LOG_ERROR("open failed");
1489 jtag_libusb_set_configuration(h->fd, 0);
1491 if (jtag_libusb_claim_interface(h->fd, 0) != ERROR_OK) {
1492 LOG_DEBUG("claim interface failed");
1496 /* wrap version for first read */
1497 switch (param->pid) {
1499 h->version.stlink = 1;
1502 h->version.stlink = 2;
1506 /* get the device version */
1507 err = stlink_usb_version(h);
1509 if (err == ERROR_OK) {
1511 } else if (h->version.stlink == 1 ||
1513 LOG_ERROR("read version failed");
1516 err = jtag_libusb_release_interface(h->fd, 0);
1517 if (err != ERROR_OK) {
1518 LOG_ERROR("release interface failed");
1522 err = jtag_libusb_reset_device(h->fd);
1523 if (err != ERROR_OK) {
1524 LOG_ERROR("reset device failed");
1528 jtag_libusb_close(h->fd);
1530 Give the device one second to settle down and
1533 usleep(1 * 1000 * 1000);
1538 /* compare usb vid/pid */
1539 if ((param->vid != h->vid) || (param->pid != h->pid))
1540 LOG_INFO("vid/pid are not identical: 0x%04X/0x%04X 0x%04X/0x%04X",
1541 param->vid, param->pid,
1544 /* check if mode is supported */
1547 switch (h->transport) {
1548 case HL_TRANSPORT_SWD:
1549 case HL_TRANSPORT_JTAG:
1550 if (h->version.jtag == 0)
1553 case HL_TRANSPORT_SWIM:
1554 if (h->version.swim == 0)
1562 if (err != ERROR_OK) {
1563 LOG_ERROR("mode (transport) not supported by device");
1567 api = h->version.jtag_api_max;
1569 /* check that user has not requested certain api version
1570 * and if they have check it is supported */
1571 if ((param->api != 0) && (param->api <= h->version.jtag_api_max)) {
1573 LOG_INFO("using stlink api v%d", api);
1576 /* set the used jtag api, this will default to the newest supported version */
1579 if (h->jtag_api >= 2 && param->trace_f && param->trace_source_hz > 0) {
1582 prescale = param->trace_source_hz > STLINK_TRACE_MAX_HZ ?
1583 (param->trace_source_hz / STLINK_TRACE_MAX_HZ) - 1 : 0;
1585 h->trace.output_f = param->trace_f;
1586 h->trace.source_hz = param->trace_source_hz;
1587 h->trace.prescale = prescale;
1590 /* initialize the debug hardware */
1591 err = stlink_usb_init_mode(h, param->connect_under_reset);
1593 if (err != ERROR_OK) {
1594 LOG_ERROR("init mode failed");
1603 stlink_usb_close(h);
1609 struct hl_layout_api_s stlink_usb_layout_api = {
1611 .open = stlink_usb_open,
1613 .close = stlink_usb_close,
1615 .idcode = stlink_usb_idcode,
1617 .state = stlink_usb_state,
1619 .reset = stlink_usb_reset,
1621 .assert_srst = stlink_usb_assert_srst,
1623 .run = stlink_usb_run,
1625 .halt = stlink_usb_halt,
1627 .step = stlink_usb_step,
1629 .read_regs = stlink_usb_read_regs,
1631 .read_reg = stlink_usb_read_reg,
1633 .write_reg = stlink_usb_write_reg,
1635 .read_mem8 = stlink_usb_read_mem8,
1637 .write_mem8 = stlink_usb_write_mem8,
1639 .read_mem32 = stlink_usb_read_mem32,
1641 .write_mem32 = stlink_usb_write_mem32,
1643 .write_debug_reg = stlink_usb_write_debug_reg