1 /* SPDX-License-Identifier: GPL-2.0-or-later */
3 /***************************************************************************
4 * Espressif USB to Jtag adapter *
5 * Copyright (C) 2020 Espressif Systems (Shanghai) Co. Ltd. *
6 ***************************************************************************/
12 #include <jtag/adapter.h>
13 #include <jtag/interface.h>
14 #include <helper/time_support.h>
15 #include <helper/bits.h>
17 #include "libusb_helper.h"
19 #define __packed __attribute__((packed))
22 Holy Crap, it's protocol documentation, and it's even vendor-provided!
24 A device that speaks this protocol has two endpoints intended for JTAG debugging: one
25 OUT for the host to send encoded commands to, one IN from which the host can read any read
26 TDO bits. The device will also respond to vendor-defined interface requests on ep0.
28 The main communication method is over the IN/OUT endpoints. The commands that are expected
29 on the OUT endpoint are one nibble wide and are processed high-nibble-first, low-nibble-second,
30 and in the order the bytes come in. Commands are defined as follows:
33 CMD_CLK [ 0 cap tdi tms ]
34 CMD_RST [ 1 0 0 srst ]
39 CMD_CLK sets the TDI and TMS lines to the value of `tdi` and `tms` and lowers, then raises, TCK. If
40 `cap` is 1, the value of TDO is captured and can be retrieved over the IN endpoint. The bytes read from
41 the IN endpoint specifically are these bits, with the lowest it in every byte captured first and the
42 bytes returned in the order the data in them was captured. The durations of TCK being high / low can
43 be set using the VEND_JTAG_SETDIV vendor-specific interface request.
45 CMD_RST controls the SRST line; as soon as the command is processed, the SRST line will be set
46 to the value of `srst`.
48 CMD_FLUSH flushes the IN endpoint; zeroes will be added to the amount of bits in the endpoint until
49 the payload is a multiple of bytes, and the data is offered to the host. If the IN endpoint has
50 no data, this effectively becomes a no-op; the endpoint won't send any 0-byte payloads.
52 CMD_RSV is reserved for future use.
54 CMD_REP repeats the last command that is not CMD_REP. The amount of times a CMD_REP command will
55 re-execute this command is (r1*2+r0)<<(2*n), where n is the amount of previous repeat commands executed
56 since the command to be repeated.
58 An example for CMD_REP: Say the host queues:
59 1. CMD_CLK - This will execute one CMD_CLK.
60 2. CMD_REP with r1=0 and r0=1 - This will execute 1. another (0*2+1)<<(2*0)=1 time.
61 3. CMD_REP with r1=1 and r0=0 - This will execute 1. another (1*2+0)<<(2*1)=4 times.
62 4. CMD_REP with r1=0 and r0=1 - This will execute 1. another (0*2+1)<<(2*2)=8 time.
63 5. CMD_FLUSH - This will flush the IN pipeline.
64 6. CMD_CLK - This will execute one CMD_CLK
65 7. CMD_REP with r1=1 and r0=0 - This will execute 6. another (1*2+0)<<(2*0)=2 times.
66 8. CMD_FLUSH - This will flush the IN pipeline.
68 Note that the net effect of the repetitions is that command 1 is executed (1+1+4+8=) 14 times and
69 command 6 is executed (1+2=) 3 times.
71 Note that the device only has a fairly limited amount of endpoint RAM. It's probably best to keep
72 an eye on the amount of bytes that are supposed to be in the IN endpoint and grab those before stuffing
73 more commands into the OUT endpoint: the OUT endpoint will not accept any more commands (writes will
74 time out) when the IN endpoint buffers are all filled up.
76 The device also supports some vendor-specific interface requests. These requests are sent as control
77 transfers on endpoint 0 to the JTAG endpoint. Note that these commands bypass the data in the OUT
78 endpoint; if timing is important, it's important that this endpoint is empty. This can be done by
79 e.g sending one CMD_CLK capturing TDI, then one CMD_FLUSH, then waiting until the bit appears on the
82 bmRequestType bRequest wValue wIndex wLength Data
83 01000000b VEND_JTAG_SETDIV [divide] interface 0 None
84 01000000b VEND_JTAG_SETIO [iobits] interface 0 None
85 11000000b VEND_JTAG_GETTDO 0 interface 1 [iostate]
86 10000000b GET_DESCRIPTOR(6) 0x2000 0 256 [jtag cap desc]
88 VEND_JTAG_SETDIV indirectly controls the speed of the TCK clock. The value written here is the length
89 of a TCK cycle, in ticks of the adapters base clock. Both the base clock value as well as the
90 minimum and maximum divider can be read from the jtag capabilities descriptor, as explained
91 below. Note that this should not be set to a value outside of the range described there,
92 otherwise results are undefined.
94 VEND_JTAG_SETIO can be controlled to directly set the IO pins. The format of [iobits] normally is
95 {11'b0, srst, trst, tck, tms, tdi}
96 Note that the first 11 0 bits are reserved for future use, current hardware ignores them.
98 VEND_JTAG_GETTDO returns one byte, of which bit 0 indicates the current state of the TDO input.
99 Note that other bits are reserved for future use and should be ignored.
101 To describe the capabilities of the JTAG adapter, a specific descriptor (0x20) can be retrieved.
102 The format of the descriptor documented below. The descriptor works in the same fashion as USB
103 descriptors: a header indicating the version and total length followed by descriptors with a
104 specific type and size. Forward compatibility is guaranteed as software can skip over an unknown
109 #define JTAG_PROTO_CAPS_VER 1 /* Version field. At the moment, only version 1 is defined. */
110 struct jtag_proto_caps_hdr {
111 uint8_t proto_ver; /* Protocol version. Expects JTAG_PROTO_CAPS_VER for now. */
112 uint8_t length; /* of this plus any following descriptors */
115 /* start of the descriptor headers */
116 #define JTAG_BUILTIN_DESCR_START_OFF 0 /* Devices with builtin usb jtag */
118 * ESP USB Bridge https://github.com/espressif/esp-usb-bridge uses string descriptor.
119 * Skip 1 byte length and 1 byte descriptor type
121 #define JTAG_EUB_DESCR_START_OFF 2 /* ESP USB Bridge */
124 Note: At the moment, there is only a speed_caps version indicating the base speed of the JTAG
125 hardware is derived from the APB bus speed of the SoC. If later on, there are standalone
126 converters using the protocol, we should define e.g. JTAG_PROTO_CAPS_SPEED_FIXED_TYPE to distinguish
129 Note: If the JTAG device has larger buffers than endpoint-size-plus-a-bit, we should have some kind
130 of caps header to assume this. If no such caps exist, assume a minimum (in) buffer of endpoint size + 4.
133 struct jtag_gen_hdr {
138 struct jtag_proto_caps_speed_apb {
139 uint8_t type; /* Type, always JTAG_PROTO_CAPS_SPEED_APB_TYPE */
140 uint8_t length; /* Length of this */
141 uint8_t apb_speed_10khz[2]; /* ABP bus speed, in 10KHz increments. Base speed is half this. */
142 uint8_t div_min[2]; /* minimum divisor (to base speed), inclusive */
143 uint8_t div_max[2]; /* maximum divisor (to base speed), inclusive */
146 #define JTAG_PROTO_CAPS_DATA_LEN 255
147 #define JTAG_PROTO_CAPS_SPEED_APB_TYPE 1
149 #define VEND_DESCR_BUILTIN_JTAG_CAPS 0x2000
151 #define VEND_JTAG_SETDIV 0
152 #define VEND_JTAG_SETIO 1
153 #define VEND_JTAG_GETTDO 2
154 #define VEND_JTAG_SET_CHIPID 3
156 #define VEND_JTAG_SETIO_TDI BIT(0)
157 #define VEND_JTAG_SETIO_TMS BIT(1)
158 #define VEND_JTAG_SETIO_TCK BIT(2)
159 #define VEND_JTAG_SETIO_TRST BIT(3)
160 #define VEND_JTAG_SETIO_SRST BIT(4)
162 #define CMD_CLK(cap, tdi, tms) ((cap ? BIT(2) : 0) | (tms ? BIT(1) : 0) | (tdi ? BIT(0) : 0))
163 #define CMD_RST(srst) (0x8 | (srst ? BIT(0) : 0))
164 #define CMD_FLUSH 0xA
166 #define CMD_REP(r) (0xC + ((r) & 3))
168 /* The internal repeats register is 10 bits, which means we can have 5 repeat commands in a
169 *row at max. This translates to ('b1111111111+1=)1024 reps max. */
170 #define CMD_REP_MAX_REPS 1024
172 /* Currently we only support one USB device. */
173 #define USB_CONFIGURATION 0
175 /* Buffer size; is equal to the endpoint size. In bytes
176 * TODO for future adapters: read from device configuration? */
178 /* Out data can be buffered for longer without issues (as long as the in buffer does not overflow),
179 * so we'll use an out buffer that is much larger than the out ep size. */
180 #define OUT_BUF_SZ (OUT_EP_SZ * 32)
181 /* The in buffer cannot be larger than the device can offer, though. */
184 /* Because a series of out commands can lead to a multitude of IN_BUF_SZ-sized in packets
185 *to be read, we have multiple buffers to store those before the bitq interface reads them out. */
188 #define ESP_USB_INTERFACE 1
191 struct esp_usb_jtag {
192 struct libusb_device_handle *usb_device;
193 uint32_t base_speed_khz;
196 uint8_t out_buf[OUT_BUF_SZ];
197 unsigned int out_buf_pos_nibbles; /* write position in out_buf */
199 uint8_t in_buf[IN_BUF_CT][IN_BUF_SZ];
200 unsigned int in_buf_size_bits[IN_BUF_CT]; /* size in bits of the data stored in an in_buf */
201 unsigned int cur_in_buf_rd, cur_in_buf_wr; /* read/write index */
202 unsigned int in_buf_pos_bits; /* which bit in the in buf needs to be returned to bitq next */
204 unsigned int read_ep;
205 unsigned int write_ep;
207 unsigned int prev_cmd; /* previous command, stored here for RLEing. */
208 int prev_cmd_repct; /* Amount of repetitions of that command we have seen until now */
210 /* This is the total number of in bits we need to read, including in unsent commands */
211 unsigned int pending_in_bits;
213 unsigned int hw_in_fifo_len;
215 struct bitq_interface bitq_interface;
218 /* For now, we only use one static private struct. Technically, we can re-work this, but I don't think
219 * OpenOCD supports multiple JTAG adapters anyway. */
220 static struct esp_usb_jtag esp_usb_jtag_priv;
221 static struct esp_usb_jtag *priv = &esp_usb_jtag_priv;
223 static int esp_usb_vid;
224 static int esp_usb_pid;
225 static int esp_usb_jtag_caps;
226 static int esp_usb_target_chip_id;
228 static int esp_usb_jtag_init(void);
229 static int esp_usb_jtag_quit(void);
231 /* Try to receive from USB endpoint into the current priv->in_buf */
232 static int esp_usb_jtag_recv_buf(void)
234 if (priv->in_buf_size_bits[priv->cur_in_buf_wr] != 0)
235 LOG_ERROR("esp_usb_jtag: IN buffer overflow! (%d, size %d)",
237 priv->in_buf_size_bits[priv->cur_in_buf_wr]);
239 unsigned int recvd = 0, ct = (priv->pending_in_bits + 7) / 8;
243 /* Note that the adapters IN EP specifically does *not* usually generate 0-byte in
244 * packets if there has been no data since the last flush.
245 * As such, we don't need (and shouldn't) try to read it. */
249 priv->in_buf_size_bits[priv->cur_in_buf_wr] = 0;
252 int ret = jtag_libusb_bulk_read(priv->usb_device,
254 (char *)priv->in_buf[priv->cur_in_buf_wr] + recvd,
256 LIBUSB_TIMEOUT_MS, /*ms*/
258 if (ret != ERROR_OK || tr == 0) {
259 /* Sometimes the hardware returns 0 bytes instead of NAKking the transaction. Ignore this. */
264 /* Huh, short read? */
265 LOG_DEBUG("esp_usb_jtag: usb received only %d out of %d bytes.", tr, ct);
267 /* Adjust the amount of bits we still expect to read from the USB device after this. */
268 unsigned int bits_in_buf = priv->pending_in_bits; /* initially assume we read
269 * everything that was pending */
270 if (bits_in_buf > tr * 8)
271 bits_in_buf = tr * 8; /* ...but correct that if that was not the case. */
272 priv->pending_in_bits -= bits_in_buf;
273 priv->in_buf_size_bits[priv->cur_in_buf_wr] += bits_in_buf;
276 /* next in buffer for the next time. */
277 priv->cur_in_buf_wr++;
278 if (priv->cur_in_buf_wr == IN_BUF_CT)
279 priv->cur_in_buf_wr = 0;
280 LOG_DEBUG_IO("esp_usb_jtag: In ep: received %d bytes; %d bytes (%d bits) left.", recvd,
281 (priv->pending_in_bits + 7) / 8, priv->pending_in_bits);
285 /* Sends priv->out_buf to the USB device. */
286 static int esp_usb_jtag_send_buf(void)
288 unsigned int ct = priv->out_buf_pos_nibbles / 2;
289 unsigned int written = 0;
291 while (written < ct) {
292 int tr = 0, ret = jtag_libusb_bulk_write(priv->usb_device,
294 (char *)priv->out_buf + written,
296 LIBUSB_TIMEOUT_MS, /*ms*/
298 LOG_DEBUG_IO("esp_usb_jtag: sent %d bytes.", tr);
299 if (written + tr != ct) {
300 LOG_DEBUG("esp_usb_jtag: usb sent only %d out of %d bytes.",
308 priv->out_buf_pos_nibbles = 0;
310 /* If there's more than a bufferful of data queuing up in the jtag adapters IN endpoint, empty
311 * all but one buffer. */
312 while (priv->pending_in_bits > (IN_BUF_SZ + priv->hw_in_fifo_len - 1) * 8)
313 esp_usb_jtag_recv_buf();
318 /* Simply adds a command to the buffer. Is called by the RLE encoding mechanism.
319 *Also sends the intermediate buffer if there's enough to go into one USB packet. */
320 static int esp_usb_jtag_command_add_raw(unsigned int cmd)
324 if ((priv->out_buf_pos_nibbles & 1) == 0)
325 priv->out_buf[priv->out_buf_pos_nibbles / 2] = (cmd << 4);
327 priv->out_buf[priv->out_buf_pos_nibbles / 2] |= cmd;
328 priv->out_buf_pos_nibbles++;
330 if (priv->out_buf_pos_nibbles == OUT_BUF_SZ * 2)
331 ret = esp_usb_jtag_send_buf();
332 if (ret == ERROR_OK && priv->out_buf_pos_nibbles % (OUT_EP_SZ * 2) == 0) {
333 if (priv->pending_in_bits > (IN_BUF_SZ + priv->hw_in_fifo_len - 1) * 8)
334 ret = esp_usb_jtag_send_buf();
339 /* Writes a command stream equivalent to writing `cmd` `ct` times. */
340 static int esp_usb_jtag_write_rlestream(unsigned int cmd, int ct)
342 /* Special case: stacking flush commands does not make sense (and may not make the hardware very happy) */
343 if (cmd == CMD_FLUSH)
345 /* Output previous command and repeat commands */
346 int ret = esp_usb_jtag_command_add_raw(cmd);
349 ct--; /* as the previous line already executes the command one time */
351 ret = esp_usb_jtag_command_add_raw(CMD_REP(ct & 3));
359 /* Adds a command to the buffer of things to be sent. Transparently handles RLE compression using
360 * the CMD_REP_x commands */
361 static int esp_usb_jtag_command_add(unsigned int cmd)
363 if (cmd == priv->prev_cmd && priv->prev_cmd_repct < CMD_REP_MAX_REPS) {
364 priv->prev_cmd_repct++;
366 /* We can now write out the previous command plus repeat count. */
367 if (priv->prev_cmd_repct) {
368 int ret = esp_usb_jtag_write_rlestream(priv->prev_cmd, priv->prev_cmd_repct);
372 /* Ready for new command. */
373 priv->prev_cmd = cmd;
374 priv->prev_cmd_repct = 1;
379 /* Called by bitq interface to output a bit on tdi and perhaps read a bit from tdo */
380 static int esp_usb_jtag_out(int tms, int tdi, int tdo_req)
382 int ret = esp_usb_jtag_command_add(CMD_CLK(tdo_req, tdi, tms));
386 priv->pending_in_bits++;
390 /* Called by bitq interface to flush all output commands and get returned data ready to read */
391 static int esp_usb_jtag_flush(void)
394 /*Make sure last command is written */
395 if (priv->prev_cmd_repct) {
396 ret = esp_usb_jtag_write_rlestream(priv->prev_cmd, priv->prev_cmd_repct);
400 priv->prev_cmd_repct = 0;
401 /* Flush in buffer */
402 ret = esp_usb_jtag_command_add_raw(CMD_FLUSH);
405 /* Make sure we have an even amount of commands, as we can't write a nibble by itself. */
406 if (priv->out_buf_pos_nibbles & 1) {
407 /*If not, pad with an extra FLUSH */
408 ret = esp_usb_jtag_command_add_raw(CMD_FLUSH);
412 LOG_DEBUG_IO("esp_usb_jtag: Flush!");
413 /* Send off the buffer. */
414 ret = esp_usb_jtag_send_buf();
418 /* Immediately fetch the response bits. */
419 while (priv->pending_in_bits > 0)
420 esp_usb_jtag_recv_buf();
425 /* Called by bitq interface to sleep for a determined amount of time */
426 static int esp_usb_jtag_sleep(unsigned long us)
428 esp_usb_jtag_flush();
429 /* TODO: we can sleep more precisely (for small amounts of sleep at least) by sending dummy
430 * commands to the adapter. */
435 /* Called by the bitq interface to set the various resets */
436 static int esp_usb_jtag_reset(int trst, int srst)
438 /* TODO: handle trst using setup commands. Kind-of superfluous, however, as we can also do
439 * a tap reset using tms, and it's also not implemented on other ESP32 chips with external JTAG. */
440 return esp_usb_jtag_command_add(CMD_RST(srst));
443 /* Called by bitq to see if the IN data already is returned to the host. */
444 static int esp_usb_jtag_in_rdy(void)
446 /* We read all bits in the flush() routine, so if we're here, we have bits or are at EOF. */
450 /* Read one bit from the IN data */
451 static int esp_usb_jtag_in(void)
453 if (!esp_usb_jtag_in_rdy()) {
454 LOG_ERROR("esp_usb_jtag: Eeek! bitq asked us for in data while not ready!");
457 if (priv->cur_in_buf_rd == priv->cur_in_buf_wr &&
458 priv->in_buf_size_bits[priv->cur_in_buf_rd] == 0)
461 /* Extract the bit */
462 int r = (priv->in_buf[priv->cur_in_buf_rd][priv->in_buf_pos_bits / 8] &
463 BIT(priv->in_buf_pos_bits & 7)) ? 1 : 0;
464 /* Move to next bit. */
465 priv->in_buf_pos_bits++;
466 if (priv->in_buf_pos_bits == priv->in_buf_size_bits[priv->cur_in_buf_rd]) {
467 /* No more bits in this buffer; mark as re-usable and move to next buffer. */
468 priv->in_buf_pos_bits = 0;
469 priv->in_buf_size_bits[priv->cur_in_buf_rd] = 0;/*indicate it is free again */
470 priv->cur_in_buf_rd++;
471 if (priv->cur_in_buf_rd == IN_BUF_CT)
472 priv->cur_in_buf_rd = 0;
477 static int esp_usb_jtag_init(void)
479 memset(priv, 0, sizeof(struct esp_usb_jtag));
481 const uint16_t vids[] = { esp_usb_vid, 0 }; /* must be null terminated */
482 const uint16_t pids[] = { esp_usb_pid, 0 }; /* must be null terminated */
484 bitq_interface = &priv->bitq_interface;
485 bitq_interface->out = esp_usb_jtag_out;
486 bitq_interface->flush = esp_usb_jtag_flush;
487 bitq_interface->sleep = esp_usb_jtag_sleep;
488 bitq_interface->reset = esp_usb_jtag_reset;
489 bitq_interface->in_rdy = esp_usb_jtag_in_rdy;
490 bitq_interface->in = esp_usb_jtag_in;
492 int r = jtag_libusb_open(vids, pids, &priv->usb_device, NULL);
494 LOG_ERROR("esp_usb_jtag: could not find or open device!");
498 jtag_libusb_set_configuration(priv->usb_device, USB_CONFIGURATION);
500 r = jtag_libusb_choose_interface(priv->usb_device, &priv->read_ep, &priv->write_ep,
501 LIBUSB_CLASS_VENDOR_SPEC, LIBUSB_CLASS_VENDOR_SPEC, ESP_USB_INTERFACE, LIBUSB_TRANSFER_TYPE_BULK);
503 LOG_ERROR("esp_usb_jtag: error finding/claiming JTAG interface on device!");
507 /* TODO: This is not proper way to get caps data. Two requests can be done.
508 * 1- With the minimum size required to get to know the total length of that struct,
509 * 2- Then exactly the length of that struct. */
510 uint8_t jtag_caps_desc[JTAG_PROTO_CAPS_DATA_LEN];
511 int jtag_caps_read_len = jtag_libusb_control_transfer(priv->usb_device,
512 LIBUSB_ENDPOINT_IN | LIBUSB_REQUEST_TYPE_STANDARD | LIBUSB_RECIPIENT_DEVICE,
513 LIBUSB_REQUEST_GET_DESCRIPTOR, esp_usb_jtag_caps, 0,
514 (char *)jtag_caps_desc, JTAG_PROTO_CAPS_DATA_LEN, LIBUSB_TIMEOUT_MS);
515 if (jtag_caps_read_len <= 0) {
516 LOG_ERROR("esp_usb_jtag: could not retrieve jtag_caps descriptor!");
520 /* defaults for values we normally get from the jtag caps descriptor */
521 priv->base_speed_khz = UINT32_MAX;
525 int p = esp_usb_jtag_caps ==
526 VEND_DESCR_BUILTIN_JTAG_CAPS ? JTAG_BUILTIN_DESCR_START_OFF : JTAG_EUB_DESCR_START_OFF;
528 if (p + sizeof(struct jtag_proto_caps_hdr) > (unsigned int)jtag_caps_read_len) {
529 LOG_ERROR("esp_usb_jtag: not enough data to get header");
533 struct jtag_proto_caps_hdr *hdr = (struct jtag_proto_caps_hdr *)&jtag_caps_desc[p];
534 if (hdr->proto_ver != JTAG_PROTO_CAPS_VER) {
535 LOG_ERROR("esp_usb_jtag: unknown jtag_caps descriptor version 0x%X!",
539 if (hdr->length > jtag_caps_read_len) {
540 LOG_ERROR("esp_usb_jtag: header length (%d) bigger then max read bytes (%d)",
541 hdr->length, jtag_caps_read_len);
545 p += sizeof(struct jtag_proto_caps_hdr);
547 while (p + sizeof(struct jtag_gen_hdr) < hdr->length) {
548 struct jtag_gen_hdr *dhdr = (struct jtag_gen_hdr *)&jtag_caps_desc[p];
549 if (dhdr->type == JTAG_PROTO_CAPS_SPEED_APB_TYPE) {
550 if (p + sizeof(struct jtag_proto_caps_speed_apb) < hdr->length) {
551 LOG_ERROR("esp_usb_jtag: not enough data to get caps speed");
554 struct jtag_proto_caps_speed_apb *spcap = (struct jtag_proto_caps_speed_apb *)dhdr;
555 /* base speed always is half APB speed */
556 priv->base_speed_khz = le_to_h_u16(spcap->apb_speed_10khz) * 10 / 2;
557 priv->div_min = le_to_h_u16(spcap->div_min);
558 priv->div_max = le_to_h_u16(spcap->div_max);
559 /* TODO: mark in priv that this is apb-derived and as such may change if apb
562 LOG_WARNING("esp_usb_jtag: unknown caps type 0x%X", dhdr->type);
566 if (priv->base_speed_khz == UINT32_MAX) {
567 LOG_WARNING("esp_usb_jtag: No speed caps found... using sane-ish defaults.");
568 priv->base_speed_khz = 1000;
570 LOG_INFO("esp_usb_jtag: Device found. Base speed %dKHz, div range %d to %d",
571 priv->base_speed_khz, priv->div_min, priv->div_max);
573 /* TODO: grab from (future) descriptor if we ever have a device with larger IN buffers */
574 priv->hw_in_fifo_len = 4;
576 /* inform bridge board about the connected target chip for the specific operations
577 * it is also safe to send this info to chips that have builtin usb jtag */
578 jtag_libusb_control_transfer(priv->usb_device,
579 LIBUSB_REQUEST_TYPE_VENDOR,
580 VEND_JTAG_SET_CHIPID,
581 esp_usb_target_chip_id,
590 if (priv->usb_device)
591 jtag_libusb_close(priv->usb_device);
592 bitq_interface = NULL;
593 priv->usb_device = NULL;
597 static int esp_usb_jtag_quit(void)
599 if (!priv->usb_device)
601 jtag_libusb_close(priv->usb_device);
603 bitq_interface = NULL;
607 static int esp_usb_jtag_speed_div(int divisor, int *khz)
609 *khz = priv->base_speed_khz / divisor;
613 static int esp_usb_jtag_khz(int khz, int *divisor)
616 LOG_WARNING("esp_usb_jtag: RCLK not supported");
620 *divisor = priv->base_speed_khz / khz;
621 LOG_DEBUG("Divisor for %d KHz with base clock of %d khz is %d",
623 priv->base_speed_khz,
625 if (*divisor < priv->div_min)
626 *divisor = priv->div_min;
627 if (*divisor > priv->div_max)
628 *divisor = priv->div_max;
633 static int esp_usb_jtag_speed(int divisor)
636 LOG_ERROR("esp_usb_jtag: Adaptive clocking is not supported.");
637 return ERROR_JTAG_NOT_IMPLEMENTED;
640 LOG_DEBUG("esp_usb_jtag: setting divisor %d", divisor);
641 jtag_libusb_control_transfer(priv->usb_device,
642 LIBUSB_REQUEST_TYPE_VENDOR, VEND_JTAG_SETDIV, divisor, 0, NULL, 0, LIBUSB_TIMEOUT_MS);
647 COMMAND_HANDLER(esp_usb_jtag_tdo_cmd)
650 if (!priv->usb_device)
652 int r = jtag_libusb_control_transfer(priv->usb_device,
653 LIBUSB_ENDPOINT_IN | LIBUSB_REQUEST_TYPE_VENDOR, VEND_JTAG_GETTDO, 0, 0, &tdo, 1, LIBUSB_TIMEOUT_MS);
657 command_print(CMD, "%d", tdo);
662 COMMAND_HANDLER(esp_usb_jtag_setio_cmd)
664 uint32_t tdi, tms, tck, trst, srst;
667 if (!priv->usb_device)
671 return ERROR_COMMAND_SYNTAX_ERROR;
673 COMMAND_PARSE_NUMBER(u32, CMD_ARGV[0], tdi);
674 COMMAND_PARSE_NUMBER(u32, CMD_ARGV[1], tms);
675 COMMAND_PARSE_NUMBER(u32, CMD_ARGV[2], tck);
676 COMMAND_PARSE_NUMBER(u32, CMD_ARGV[3], trst);
677 COMMAND_PARSE_NUMBER(u32, CMD_ARGV[4], srst);
679 d |= VEND_JTAG_SETIO_TDI;
681 d |= VEND_JTAG_SETIO_TMS;
683 d |= VEND_JTAG_SETIO_TCK;
685 d |= VEND_JTAG_SETIO_TRST;
687 d |= VEND_JTAG_SETIO_SRST;
689 jtag_libusb_control_transfer(priv->usb_device,
690 0x40, VEND_JTAG_SETIO, d, 0, NULL, 0, LIBUSB_TIMEOUT_MS);
695 COMMAND_HANDLER(esp_usb_jtag_vid_pid)
698 return ERROR_COMMAND_SYNTAX_ERROR;
700 COMMAND_PARSE_NUMBER(int, CMD_ARGV[0], esp_usb_vid);
701 COMMAND_PARSE_NUMBER(int, CMD_ARGV[1], esp_usb_pid);
702 LOG_INFO("esp_usb_jtag: VID set to 0x%x and PID to 0x%x", esp_usb_vid, esp_usb_pid);
707 COMMAND_HANDLER(esp_usb_jtag_caps_descriptor)
710 return ERROR_COMMAND_SYNTAX_ERROR;
712 COMMAND_PARSE_NUMBER(int, CMD_ARGV[0], esp_usb_jtag_caps);
713 LOG_INFO("esp_usb_jtag: capabilities descriptor set to 0x%x", esp_usb_jtag_caps);
718 COMMAND_HANDLER(esp_usb_jtag_chip_id)
721 return ERROR_COMMAND_SYNTAX_ERROR;
723 COMMAND_PARSE_NUMBER(int, CMD_ARGV[0], esp_usb_target_chip_id);
724 LOG_INFO("esp_usb_jtag: target chip id set to %d", esp_usb_target_chip_id);
729 static const struct command_registration esp_usb_jtag_subcommands[] = {
732 .handler = &esp_usb_jtag_tdo_cmd,
733 .mode = COMMAND_EXEC,
734 .help = "Returns the current state of the TDO line",
739 .handler = &esp_usb_jtag_setio_cmd,
740 .mode = COMMAND_EXEC,
741 .help = "Manually set the status of the output lines",
742 .usage = "tdi tms tck trst srst"
746 .handler = &esp_usb_jtag_vid_pid,
747 .mode = COMMAND_CONFIG,
748 .help = "set vendor ID and product ID for ESP usb jtag driver",
752 .name = "caps_descriptor",
753 .handler = &esp_usb_jtag_caps_descriptor,
754 .mode = COMMAND_CONFIG,
755 .help = "set jtag descriptor to read capabilities of ESP usb jtag driver",
756 .usage = "descriptor",
760 .handler = &esp_usb_jtag_chip_id,
761 .mode = COMMAND_CONFIG,
762 .help = "set chip_id to transfer to the bridge",
765 COMMAND_REGISTRATION_DONE
768 static const struct command_registration esp_usb_jtag_commands[] = {
770 .name = "espusbjtag",
772 .help = "ESP-USB-JTAG commands",
773 .chain = esp_usb_jtag_subcommands,
776 COMMAND_REGISTRATION_DONE
779 static struct jtag_interface esp_usb_jtag_interface = {
780 .supported = DEBUG_CAP_TMS_SEQ,
781 .execute_queue = bitq_execute_queue,
784 struct adapter_driver esp_usb_adapter_driver = {
785 .name = "esp_usb_jtag",
786 .transports = jtag_only,
787 .commands = esp_usb_jtag_commands,
789 .init = esp_usb_jtag_init,
790 .quit = esp_usb_jtag_quit,
791 .speed_div = esp_usb_jtag_speed_div,
792 .speed = esp_usb_jtag_speed,
793 .khz = esp_usb_jtag_khz,
795 .jtag_ops = &esp_usb_jtag_interface,