OpenOCD
esp_usb_jtag.c
Go to the documentation of this file.
1 // SPDX-License-Identifier: GPL-2.0-or-later
2 
3 /***************************************************************************
4  * Espressif USB to Jtag adapter *
5  * Copyright (C) 2020 Espressif Systems (Shanghai) Co. Ltd. *
6  ***************************************************************************/
7 
8 #ifdef HAVE_CONFIG_H
9 #include "config.h"
10 #endif
11 
12 #include <jtag/adapter.h>
13 #include <jtag/interface.h>
14 #include <helper/time_support.h>
15 #include <helper/bits.h>
16 #include "bitq.h"
17 #include "libusb_helper.h"
18 
19 /*
20 Holy Crap, it's protocol documentation, and it's even vendor-provided!
21 
22 A device that speaks this protocol has two endpoints intended for JTAG debugging: one
23 OUT for the host to send encoded commands to, one IN from which the host can read any read
24 TDO bits. The device will also respond to vendor-defined interface requests on ep0.
25 
26 The main communication method is over the IN/OUT endpoints. The commands that are expected
27 on the OUT endpoint are one nibble wide and are processed high-nibble-first, low-nibble-second,
28 and in the order the bytes come in. Commands are defined as follows:
29 
30  bit 3 2 1 0
31 CMD_CLK [ 0 cap tdi tms ]
32 CMD_RST [ 1 0 0 srst ]
33 CMD_FLUSH [ 1 0 1 0 ]
34 CMD_RSV [ 1 0 1 1 ]
35 CMD_REP [ 1 1 R1 R0 ]
36 
37 CMD_CLK sets the TDI and TMS lines to the value of `tdi` and `tms` and lowers, then raises, TCK. If
38 `cap` is 1, the value of TDO is captured and can be retrieved over the IN endpoint. The bytes read from
39 the IN endpoint specifically are these bits, with the lowest it in every byte captured first and the
40 bytes returned in the order the data in them was captured. The durations of TCK being high / low can
41 be set using the VEND_JTAG_SETDIV vendor-specific interface request.
42 
43 CMD_RST controls the SRST line; as soon as the command is processed, the SRST line will be set
44 to the value of `srst`.
45 
46 CMD_FLUSH flushes the IN endpoint; zeroes will be added to the amount of bits in the endpoint until
47 the payload is a multiple of bytes, and the data is offered to the host. If the IN endpoint has
48 no data, this effectively becomes a no-op; the endpoint won't send any 0-byte payloads.
49 
50 CMD_RSV is reserved for future use.
51 
52 CMD_REP repeats the last command that is not CMD_REP. The amount of times a CMD_REP command will
53 re-execute this command is (r1*2+r0)<<(2*n), where n is the amount of previous repeat commands executed
54 since the command to be repeated.
55 
56 An example for CMD_REP: Say the host queues:
57 1. CMD_CLK - This will execute one CMD_CLK.
58 2. CMD_REP with r1=0 and r0=1 - This will execute 1. another (0*2+1)<<(2*0)=1 time.
59 3. CMD_REP with r1=1 and r0=0 - This will execute 1. another (1*2+0)<<(2*1)=4 times.
60 4. CMD_REP with r1=0 and r0=1 - This will execute 1. another (0*2+1)<<(2*2)=8 time.
61 5. CMD_FLUSH - This will flush the IN pipeline.
62 6. CMD_CLK - This will execute one CMD_CLK
63 7. CMD_REP with r1=1 and r0=0 - This will execute 6. another (1*2+0)<<(2*0)=2 times.
64 8. CMD_FLUSH - This will flush the IN pipeline.
65 
66 Note that the net effect of the repetitions is that command 1 is executed (1+1+4+8=) 14 times and
67 command 6 is executed (1+2=) 3 times.
68 
69 Note that the device only has a fairly limited amount of endpoint RAM. It's probably best to keep
70 an eye on the amount of bytes that are supposed to be in the IN endpoint and grab those before stuffing
71 more commands into the OUT endpoint: the OUT endpoint will not accept any more commands (writes will
72 time out) when the IN endpoint buffers are all filled up.
73 
74 The device also supports some vendor-specific interface requests. These requests are sent as control
75 transfers on endpoint 0 to the JTAG endpoint. Note that these commands bypass the data in the OUT
76 endpoint; if timing is important, it's important that this endpoint is empty. This can be done by
77 e.g sending one CMD_CLK capturing TDI, then one CMD_FLUSH, then waiting until the bit appears on the
78 IN endpoint.
79 
80 bmRequestType bRequest wValue wIndex wLength Data
81 01000000b VEND_JTAG_SETDIV [divide] interface 0 None
82 01000000b VEND_JTAG_SETIO [iobits] interface 0 None
83 11000000b VEND_JTAG_GETTDO 0 interface 1 [iostate]
84 10000000b GET_DESCRIPTOR(6) 0x2000 0 256 [jtag cap desc]
85 
86 VEND_JTAG_SETDIV indirectly controls the speed of the TCK clock. The value written here is the length
87 of a TCK cycle, in ticks of the adapters base clock. Both the base clock value as well as the
88 minimum and maximum divider can be read from the jtag capabilities descriptor, as explained
89 below. Note that this should not be set to a value outside of the range described there,
90 otherwise results are undefined.
91 
92 VEND_JTAG_SETIO can be controlled to directly set the IO pins. The format of [iobits] normally is
93 {11'b0, srst, trst, tck, tms, tdi}
94 Note that the first 11 0 bits are reserved for future use, current hardware ignores them.
95 
96 VEND_JTAG_GETTDO returns one byte, of which bit 0 indicates the current state of the TDO input.
97 Note that other bits are reserved for future use and should be ignored.
98 
99 To describe the capabilities of the JTAG adapter, a specific descriptor (0x20) can be retrieved.
100 The format of the descriptor documented below. The descriptor works in the same fashion as USB
101 descriptors: a header indicating the version and total length followed by descriptors with a
102 specific type and size. Forward compatibility is guaranteed as software can skip over an unknown
103 descriptor.
104 
105 */
106 
107 #define JTAG_PROTO_CAPS_VER 1 /* Version field. At the moment, only version 1 is defined. */
109  uint8_t proto_ver; /* Protocol version. Expects JTAG_PROTO_CAPS_VER for now. */
110  uint8_t length; /* of this plus any following descriptors */
111 } __attribute__((packed));
112 
113 /* start of the descriptor headers */
114 #define JTAG_BUILTIN_DESCR_START_OFF 0 /* Devices with builtin usb jtag */
115 /*
116 * ESP USB Bridge https://github.com/espressif/esp-usb-bridge uses string descriptor.
117 * Skip 1 byte length and 1 byte descriptor type
118 */
119 #define JTAG_EUB_DESCR_START_OFF 2 /* ESP USB Bridge */
120 
121 /*
122 Note: At the moment, there is only a speed_caps version indicating the base speed of the JTAG
123 hardware is derived from the APB bus speed of the SoC. If later on, there are standalone
124 converters using the protocol, we should define e.g. JTAG_PROTO_CAPS_SPEED_FIXED_TYPE to distinguish
125 between the two.
126 
127 Note: If the JTAG device has larger buffers than endpoint-size-plus-a-bit, we should have some kind
128 of caps header to assume this. If no such caps exist, assume a minimum (in) buffer of endpoint size + 4.
129 */
130 
131 struct jtag_gen_hdr {
132  uint8_t type;
133  uint8_t length;
134 } __attribute__((packed));
135 
137  uint8_t type; /* Type, always JTAG_PROTO_CAPS_SPEED_APB_TYPE */
138  uint8_t length; /* Length of this */
139  uint8_t apb_speed_10khz[2]; /* ABP bus speed, in 10KHz increments. Base speed is half this. */
140  uint8_t div_min[2]; /* minimum divisor (to base speed), inclusive */
141  uint8_t div_max[2]; /* maximum divisor (to base speed), inclusive */
142 } __attribute__((packed));
143 
144 #define JTAG_PROTO_CAPS_DATA_LEN 255
145 #define JTAG_PROTO_CAPS_SPEED_APB_TYPE 1
146 
147 #define VEND_DESCR_BUILTIN_JTAG_CAPS 0x2000
148 
149 #define VEND_JTAG_SETDIV 0
150 #define VEND_JTAG_SETIO 1
151 #define VEND_JTAG_GETTDO 2
152 #define VEND_JTAG_SET_CHIPID 3
153 
154 #define VEND_JTAG_SETIO_TDI BIT(0)
155 #define VEND_JTAG_SETIO_TMS BIT(1)
156 #define VEND_JTAG_SETIO_TCK BIT(2)
157 #define VEND_JTAG_SETIO_TRST BIT(3)
158 #define VEND_JTAG_SETIO_SRST BIT(4)
159 
160 #define CMD_CLK(cap, tdi, tms) ((cap ? BIT(2) : 0) | (tms ? BIT(1) : 0) | (tdi ? BIT(0) : 0))
161 #define CMD_RST(srst) (0x8 | (srst ? BIT(0) : 0))
162 #define CMD_FLUSH 0xA
163 #define CMD_RSVD 0xB
164 #define CMD_REP(r) (0xC + ((r) & 3))
165 
166 /* The internal repeats register is 10 bits, which means we can have 5 repeat commands in a
167  *row at max. This translates to ('b1111111111+1=)1024 reps max. */
168 #define CMD_REP_MAX_REPS 1024
169 
170 /* Currently we only support one USB device. */
171 #define USB_CONFIGURATION 0
172 
173 /* Buffer size; is equal to the endpoint size. In bytes
174  * TODO for future adapters: read from device configuration? */
175 #define OUT_EP_SZ 64
176 /* Out data can be buffered for longer without issues (as long as the in buffer does not overflow),
177  * so we'll use an out buffer that is much larger than the out ep size. */
178 #define OUT_BUF_SZ (OUT_EP_SZ * 32)
179 /* The in buffer cannot be larger than the device can offer, though. */
180 #define IN_BUF_SZ 64
181 
182 /* Because a series of out commands can lead to a multitude of IN_BUF_SZ-sized in packets
183  *to be read, we have multiple buffers to store those before the bitq interface reads them out. */
184 #define IN_BUF_CT 8
185 
186 #define ESP_USB_INTERFACE 1
187 
188 /* Private data */
189 struct esp_usb_jtag {
190  struct libusb_device_handle *usb_device;
191  uint32_t base_speed_khz;
192  uint16_t div_min;
193  uint16_t div_max;
194  uint8_t out_buf[OUT_BUF_SZ];
195  unsigned int out_buf_pos_nibbles; /* write position in out_buf */
196 
198  unsigned int in_buf_size_bits[IN_BUF_CT]; /* size in bits of the data stored in an in_buf */
199  unsigned int cur_in_buf_rd, cur_in_buf_wr; /* read/write index */
200  unsigned int in_buf_pos_bits; /* which bit in the in buf needs to be returned to bitq next */
201 
202  unsigned int read_ep;
203  unsigned int write_ep;
204 
205  unsigned int prev_cmd; /* previous command, stored here for RLEing. */
206  int prev_cmd_repct; /* Amount of repetitions of that command we have seen until now */
207 
208  /* This is the total number of in bits we need to read, including in unsent commands */
209  unsigned int pending_in_bits;
210 
211  unsigned int hw_in_fifo_len;
212 
214 };
215 
216 /* For now, we only use one static private struct. Technically, we can re-work this, but I don't think
217  * OpenOCD supports multiple JTAG adapters anyway. */
218 static struct esp_usb_jtag esp_usb_jtag_priv;
220 
221 static int esp_usb_vid;
222 static int esp_usb_pid;
223 static int esp_usb_jtag_caps;
225 
226 static int esp_usb_jtag_init(void);
227 static int esp_usb_jtag_quit(void);
228 
229 /* Try to receive from USB endpoint into the current priv->in_buf */
230 static int esp_usb_jtag_recv_buf(void)
231 {
233  LOG_ERROR("esp_usb_jtag: IN buffer overflow! (%d, size %d)",
236 
237  unsigned int recvd = 0, ct = (priv->pending_in_bits + 7) / 8;
238  if (ct > IN_BUF_SZ)
239  ct = IN_BUF_SZ;
240  if (ct == 0) {
241  /* Note that the adapters IN EP specifically does *not* usually generate 0-byte in
242  * packets if there has been no data since the last flush.
243  * As such, we don't need (and shouldn't) try to read it. */
244  return ERROR_OK;
245  }
246 
248  while (recvd < ct) {
249  unsigned int tr;
251  priv->read_ep,
252  (char *)priv->in_buf[priv->cur_in_buf_wr] + recvd,
253  ct,
254  LIBUSB_TIMEOUT_MS, /*ms*/
255  (int *)&tr);
256  if (ret != ERROR_OK || tr == 0) {
257  /* Sometimes the hardware returns 0 bytes instead of NAKking the transaction. Ignore this. */
258  return ERROR_FAIL;
259  }
260 
261  if (tr != ct) {
262  /* Huh, short read? */
263  LOG_DEBUG("esp_usb_jtag: usb received only %d out of %d bytes.", tr, ct);
264  }
265  /* Adjust the amount of bits we still expect to read from the USB device after this. */
266  unsigned int bits_in_buf = priv->pending_in_bits; /* initially assume we read
267  * everything that was pending */
268  if (bits_in_buf > tr * 8)
269  bits_in_buf = tr * 8; /* ...but correct that if that was not the case. */
270  priv->pending_in_bits -= bits_in_buf;
271  priv->in_buf_size_bits[priv->cur_in_buf_wr] += bits_in_buf;
272  recvd += tr;
273  }
274  /* next in buffer for the next time. */
275  priv->cur_in_buf_wr++;
276  if (priv->cur_in_buf_wr == IN_BUF_CT)
277  priv->cur_in_buf_wr = 0;
278  LOG_DEBUG_IO("esp_usb_jtag: In ep: received %d bytes; %d bytes (%d bits) left.", recvd,
280  return ERROR_OK;
281 }
282 
283 /* Sends priv->out_buf to the USB device. */
284 static int esp_usb_jtag_send_buf(void)
285 {
286  unsigned int ct = priv->out_buf_pos_nibbles / 2;
287  unsigned int written = 0;
288 
289  while (written < ct) {
290  int tr = 0, ret = jtag_libusb_bulk_write(priv->usb_device,
291  priv->write_ep,
292  (char *)priv->out_buf + written,
293  ct - written,
294  LIBUSB_TIMEOUT_MS, /*ms*/
295  &tr);
296  LOG_DEBUG_IO("esp_usb_jtag: sent %d bytes.", tr);
297  if (written + tr != ct) {
298  LOG_DEBUG("esp_usb_jtag: usb sent only %d out of %d bytes.",
299  written + tr,
300  ct);
301  }
302  if (ret != ERROR_OK)
303  return ret;
304  written += tr;
305  }
307 
308  /* If there's more than a bufferful of data queuing up in the jtag adapters IN endpoint, empty
309  * all but one buffer. */
310  while (priv->pending_in_bits > (IN_BUF_SZ + priv->hw_in_fifo_len - 1) * 8)
312 
313  return ERROR_OK;
314 }
315 
316 /* Simply adds a command to the buffer. Is called by the RLE encoding mechanism.
317  *Also sends the intermediate buffer if there's enough to go into one USB packet. */
318 static int esp_usb_jtag_command_add_raw(unsigned int cmd)
319 {
320  int ret = ERROR_OK;
321 
322  if ((priv->out_buf_pos_nibbles & 1) == 0)
323  priv->out_buf[priv->out_buf_pos_nibbles / 2] = (cmd << 4);
324  else
327 
328  if (priv->out_buf_pos_nibbles == OUT_BUF_SZ * 2)
329  ret = esp_usb_jtag_send_buf();
330  if (ret == ERROR_OK && priv->out_buf_pos_nibbles % (OUT_EP_SZ * 2) == 0) {
331  if (priv->pending_in_bits > (IN_BUF_SZ + priv->hw_in_fifo_len - 1) * 8)
332  ret = esp_usb_jtag_send_buf();
333  }
334  return ret;
335 }
336 
337 /* Writes a command stream equivalent to writing `cmd` `ct` times. */
338 static int esp_usb_jtag_write_rlestream(unsigned int cmd, int ct)
339 {
340  /* Special case: stacking flush commands does not make sense (and may not make the hardware very happy) */
341  if (cmd == CMD_FLUSH)
342  ct = 1;
343  /* Output previous command and repeat commands */
345  if (ret != ERROR_OK)
346  return ret;
347  ct--; /* as the previous line already executes the command one time */
348  while (ct > 0) {
349  ret = esp_usb_jtag_command_add_raw(CMD_REP(ct & 3));
350  if (ret != ERROR_OK)
351  return ret;
352  ct >>= 2;
353  }
354  return ERROR_OK;
355 }
356 
357 /* Adds a command to the buffer of things to be sent. Transparently handles RLE compression using
358  * the CMD_REP_x commands */
359 static int esp_usb_jtag_command_add(unsigned int cmd)
360 {
362  priv->prev_cmd_repct++;
363  } else {
364  /* We can now write out the previous command plus repeat count. */
365  if (priv->prev_cmd_repct) {
367  if (ret != ERROR_OK)
368  return ret;
369  }
370  /* Ready for new command. */
371  priv->prev_cmd = cmd;
372  priv->prev_cmd_repct = 1;
373  }
374  return ERROR_OK;
375 }
376 
377 /* Called by bitq interface to output a bit on tdi and perhaps read a bit from tdo */
378 static int esp_usb_jtag_out(int tms, int tdi, int tdo_req)
379 {
380  int ret = esp_usb_jtag_command_add(CMD_CLK(tdo_req, tdi, tms));
381  if (ret != ERROR_OK)
382  return ret;
383  if (tdo_req)
385  return ERROR_OK;
386 }
387 
388 /* Called by bitq interface to flush all output commands and get returned data ready to read */
389 static int esp_usb_jtag_flush(void)
390 {
391  int ret;
392  /*Make sure last command is written */
393  if (priv->prev_cmd_repct) {
395  if (ret != ERROR_OK)
396  return ret;
397  }
398  priv->prev_cmd_repct = 0;
399  /* Flush in buffer */
401  if (ret != ERROR_OK)
402  return ret;
403  /* Make sure we have an even amount of commands, as we can't write a nibble by itself. */
404  if (priv->out_buf_pos_nibbles & 1) {
405  /*If not, pad with an extra FLUSH */
407  if (ret != ERROR_OK)
408  return ret;
409  }
410  LOG_DEBUG_IO("esp_usb_jtag: Flush!");
411  /* Send off the buffer. */
412  ret = esp_usb_jtag_send_buf();
413  if (ret != ERROR_OK)
414  return ret;
415 
416  /* Immediately fetch the response bits. */
417  while (priv->pending_in_bits > 0)
419 
420  return ERROR_OK;
421 }
422 
423 /* Called by bitq interface to sleep for a determined amount of time */
424 static int esp_usb_jtag_sleep(unsigned long us)
425 {
427  /* TODO: we can sleep more precisely (for small amounts of sleep at least) by sending dummy
428  * commands to the adapter. */
429  jtag_sleep(us);
430  return 0;
431 }
432 
433 /* Called by the bitq interface to set the various resets */
434 static int esp_usb_jtag_reset(int trst, int srst)
435 {
436  /* TODO: handle trst using setup commands. Kind-of superfluous, however, as we can also do
437  * a tap reset using tms, and it's also not implemented on other ESP32 chips with external JTAG. */
438  return esp_usb_jtag_command_add(CMD_RST(srst));
439 }
440 
441 /* Called by bitq to see if the IN data already is returned to the host. */
442 static int esp_usb_jtag_in_rdy(void)
443 {
444  /* We read all bits in the flush() routine, so if we're here, we have bits or are at EOF. */
445  return 1;
446 }
447 
448 /* Read one bit from the IN data */
449 static int esp_usb_jtag_in(void)
450 {
451  if (!esp_usb_jtag_in_rdy()) {
452  LOG_ERROR("esp_usb_jtag: Eeek! bitq asked us for in data while not ready!");
453  return -1;
454  }
457  return -1;
458 
459  /* Extract the bit */
460  int r = (priv->in_buf[priv->cur_in_buf_rd][priv->in_buf_pos_bits / 8] &
461  BIT(priv->in_buf_pos_bits & 7)) ? 1 : 0;
462  /* Move to next bit. */
465  /* No more bits in this buffer; mark as re-usable and move to next buffer. */
466  priv->in_buf_pos_bits = 0;
467  priv->in_buf_size_bits[priv->cur_in_buf_rd] = 0;/*indicate it is free again */
468  priv->cur_in_buf_rd++;
469  if (priv->cur_in_buf_rd == IN_BUF_CT)
470  priv->cur_in_buf_rd = 0;
471  }
472  return r;
473 }
474 
475 static int esp_usb_jtag_init(void)
476 {
477  memset(priv, 0, sizeof(struct esp_usb_jtag));
478 
479  const uint16_t vids[] = { esp_usb_vid, 0 }; /* must be null terminated */
480  const uint16_t pids[] = { esp_usb_pid, 0 }; /* must be null terminated */
481 
489 
490  int r = jtag_libusb_open(vids, pids, &priv->usb_device, NULL);
491  if (r != ERROR_OK) {
492  LOG_ERROR("esp_usb_jtag: could not find or open device!");
493  goto out;
494  }
495 
497 
499  LIBUSB_CLASS_VENDOR_SPEC, LIBUSB_CLASS_VENDOR_SPEC, ESP_USB_INTERFACE, LIBUSB_TRANSFER_TYPE_BULK);
500  if (r != ERROR_OK) {
501  LOG_ERROR("esp_usb_jtag: error finding/claiming JTAG interface on device!");
502  goto out;
503  }
504 
505  /* TODO: This is not proper way to get caps data. Two requests can be done.
506  * 1- With the minimum size required to get to know the total length of that struct,
507  * 2- Then exactly the length of that struct. */
508  uint8_t jtag_caps_desc[JTAG_PROTO_CAPS_DATA_LEN];
509  int jtag_caps_read_len = jtag_libusb_control_transfer(priv->usb_device,
510  LIBUSB_ENDPOINT_IN | LIBUSB_REQUEST_TYPE_STANDARD | LIBUSB_RECIPIENT_DEVICE,
511  LIBUSB_REQUEST_GET_DESCRIPTOR, esp_usb_jtag_caps, 0,
512  (char *)jtag_caps_desc, JTAG_PROTO_CAPS_DATA_LEN, LIBUSB_TIMEOUT_MS);
513  if (jtag_caps_read_len <= 0) {
514  LOG_ERROR("esp_usb_jtag: could not retrieve jtag_caps descriptor!");
515  goto out;
516  }
517 
518  /* defaults for values we normally get from the jtag caps descriptor */
519  priv->base_speed_khz = UINT32_MAX;
520  priv->div_min = 1;
521  priv->div_max = 1;
522 
523  int p = esp_usb_jtag_caps ==
525 
526  if (p + sizeof(struct jtag_proto_caps_hdr) > (unsigned int)jtag_caps_read_len) {
527  LOG_ERROR("esp_usb_jtag: not enough data to get header");
528  goto out;
529  }
530 
531  struct jtag_proto_caps_hdr *hdr = (struct jtag_proto_caps_hdr *)&jtag_caps_desc[p];
532  if (hdr->proto_ver != JTAG_PROTO_CAPS_VER) {
533  LOG_ERROR("esp_usb_jtag: unknown jtag_caps descriptor version 0x%X!",
534  hdr->proto_ver);
535  goto out;
536  }
537  if (hdr->length > jtag_caps_read_len) {
538  LOG_ERROR("esp_usb_jtag: header length (%d) bigger then max read bytes (%d)",
539  hdr->length, jtag_caps_read_len);
540  goto out;
541  }
542 
543  p += sizeof(struct jtag_proto_caps_hdr);
544 
545  while (p + sizeof(struct jtag_gen_hdr) < hdr->length) {
546  struct jtag_gen_hdr *dhdr = (struct jtag_gen_hdr *)&jtag_caps_desc[p];
547  if (dhdr->type == JTAG_PROTO_CAPS_SPEED_APB_TYPE) {
548  if (p + sizeof(struct jtag_proto_caps_speed_apb) < hdr->length) {
549  LOG_ERROR("esp_usb_jtag: not enough data to get caps speed");
550  goto out;
551  }
552  struct jtag_proto_caps_speed_apb *spcap = (struct jtag_proto_caps_speed_apb *)dhdr;
553  /* base speed always is half APB speed */
554  priv->base_speed_khz = le_to_h_u16(spcap->apb_speed_10khz) * 10 / 2;
555  priv->div_min = le_to_h_u16(spcap->div_min);
556  priv->div_max = le_to_h_u16(spcap->div_max);
557  /* TODO: mark in priv that this is apb-derived and as such may change if apb
558  * ever changes? */
559  } else {
560  LOG_WARNING("esp_usb_jtag: unknown caps type 0x%X", dhdr->type);
561  }
562  p += dhdr->length;
563  }
564  if (priv->base_speed_khz == UINT32_MAX) {
565  LOG_WARNING("esp_usb_jtag: No speed caps found... using sane-ish defaults.");
566  priv->base_speed_khz = 1000;
567  }
568  LOG_INFO("esp_usb_jtag: Device found. Base speed %dKHz, div range %d to %d",
570 
571  /* TODO: grab from (future) descriptor if we ever have a device with larger IN buffers */
572  priv->hw_in_fifo_len = 4;
573 
574  /* inform bridge board about the connected target chip for the specific operations
575  * it is also safe to send this info to chips that have builtin usb jtag */
577  LIBUSB_REQUEST_TYPE_VENDOR,
580  0,
581  NULL,
582  0,
584 
585  return ERROR_OK;
586 
587 out:
588  if (priv->usb_device)
591  priv->usb_device = NULL;
592  return ERROR_FAIL;
593 }
594 
595 static int esp_usb_jtag_quit(void)
596 {
597  if (!priv->usb_device)
598  return ERROR_OK;
600  bitq_cleanup();
602  return ERROR_OK;
603 }
604 
605 static int esp_usb_jtag_speed_div(int divisor, int *khz)
606 {
607  *khz = priv->base_speed_khz / divisor;
608  return ERROR_OK;
609 }
610 
611 static int esp_usb_jtag_khz(int khz, int *divisor)
612 {
613  if (khz == 0) {
614  LOG_WARNING("esp_usb_jtag: RCLK not supported");
615  return ERROR_FAIL;
616  }
617 
618  *divisor = priv->base_speed_khz / khz;
619  LOG_DEBUG("Divisor for %d KHz with base clock of %d khz is %d",
620  khz,
622  *divisor);
623  if (*divisor < priv->div_min)
624  *divisor = priv->div_min;
625  if (*divisor > priv->div_max)
626  *divisor = priv->div_max;
627 
628  return ERROR_OK;
629 }
630 
631 static int esp_usb_jtag_speed(int divisor)
632 {
633  if (divisor == 0) {
634  LOG_ERROR("esp_usb_jtag: Adaptive clocking is not supported.");
636  }
637 
638  LOG_DEBUG("esp_usb_jtag: setting divisor %d", divisor);
640  LIBUSB_REQUEST_TYPE_VENDOR, VEND_JTAG_SETDIV, divisor, 0, NULL, 0, LIBUSB_TIMEOUT_MS);
641 
642  return ERROR_OK;
643 }
644 
645 COMMAND_HANDLER(esp_usb_jtag_tdo_cmd)
646 {
647  char tdo;
648  if (!priv->usb_device)
649  return ERROR_FAIL;
651  LIBUSB_ENDPOINT_IN | LIBUSB_REQUEST_TYPE_VENDOR, VEND_JTAG_GETTDO, 0, 0, &tdo, 1, LIBUSB_TIMEOUT_MS);
652  if (r < 1)
653  return r;
654 
655  command_print(CMD, "%d", tdo);
656 
657  return ERROR_OK;
658 }
659 
660 COMMAND_HANDLER(esp_usb_jtag_setio_cmd)
661 {
662  uint32_t tdi, tms, tck, trst, srst;
663  uint16_t d = 0;
664 
665  if (!priv->usb_device)
666  return ERROR_FAIL;
667 
668  if (CMD_ARGC != 5)
670 
671  COMMAND_PARSE_NUMBER(u32, CMD_ARGV[0], tdi);
672  COMMAND_PARSE_NUMBER(u32, CMD_ARGV[1], tms);
673  COMMAND_PARSE_NUMBER(u32, CMD_ARGV[2], tck);
674  COMMAND_PARSE_NUMBER(u32, CMD_ARGV[3], trst);
675  COMMAND_PARSE_NUMBER(u32, CMD_ARGV[4], srst);
676  if (tdi)
677  d |= VEND_JTAG_SETIO_TDI;
678  if (tms)
679  d |= VEND_JTAG_SETIO_TMS;
680  if (tck)
681  d |= VEND_JTAG_SETIO_TCK;
682  if (trst)
684  if (srst)
686 
688  0x40, VEND_JTAG_SETIO, d, 0, NULL, 0, LIBUSB_TIMEOUT_MS);
689 
690  return ERROR_OK;
691 }
692 
693 COMMAND_HANDLER(esp_usb_jtag_vid_pid)
694 {
695  if (CMD_ARGC != 2)
697 
700  LOG_INFO("esp_usb_jtag: VID set to 0x%x and PID to 0x%x", esp_usb_vid, esp_usb_pid);
701 
702  return ERROR_OK;
703 }
704 
705 COMMAND_HANDLER(esp_usb_jtag_caps_descriptor)
706 {
707  if (CMD_ARGC != 1)
709 
711  LOG_INFO("esp_usb_jtag: capabilities descriptor set to 0x%x", esp_usb_jtag_caps);
712 
713  return ERROR_OK;
714 }
715 
716 COMMAND_HANDLER(esp_usb_jtag_chip_id)
717 {
718  if (CMD_ARGC != 1)
720 
722  LOG_INFO("esp_usb_jtag: target chip id set to %d", esp_usb_target_chip_id);
723 
724  return ERROR_OK;
725 }
726 
727 static const struct command_registration esp_usb_jtag_subcommands[] = {
728  {
729  .name = "tdo",
730  .handler = &esp_usb_jtag_tdo_cmd,
731  .mode = COMMAND_EXEC,
732  .help = "Returns the current state of the TDO line",
733  .usage = "",
734  },
735  {
736  .name = "setio",
737  .handler = &esp_usb_jtag_setio_cmd,
738  .mode = COMMAND_EXEC,
739  .help = "Manually set the status of the output lines",
740  .usage = "tdi tms tck trst srst"
741  },
742  {
743  .name = "vid_pid",
744  .handler = &esp_usb_jtag_vid_pid,
745  .mode = COMMAND_CONFIG,
746  .help = "set vendor ID and product ID for ESP usb jtag driver",
747  .usage = "vid pid",
748  },
749  {
750  .name = "caps_descriptor",
751  .handler = &esp_usb_jtag_caps_descriptor,
752  .mode = COMMAND_CONFIG,
753  .help = "set jtag descriptor to read capabilities of ESP usb jtag driver",
754  .usage = "descriptor",
755  },
756  {
757  .name = "chip_id",
758  .handler = &esp_usb_jtag_chip_id,
759  .mode = COMMAND_CONFIG,
760  .help = "set chip_id to transfer to the bridge",
761  .usage = "chip_id",
762  },
764 };
765 
766 static const struct command_registration esp_usb_jtag_commands[] = {
767  {
768  .name = "espusbjtag",
769  .mode = COMMAND_ANY,
770  .help = "ESP-USB-JTAG commands",
771  .chain = esp_usb_jtag_subcommands,
772  .usage = "",
773  },
775 };
776 
777 static struct jtag_interface esp_usb_jtag_interface = {
779  .execute_queue = bitq_execute_queue,
780 };
781 
783  .name = "esp_usb_jtag",
784  .transports = jtag_only,
785  .commands = esp_usb_jtag_commands,
786 
787  .init = esp_usb_jtag_init,
788  .quit = esp_usb_jtag_quit,
789  .speed_div = esp_usb_jtag_speed_div,
790  .speed = esp_usb_jtag_speed,
791  .khz = esp_usb_jtag_khz,
792 
793  .jtag_ops = &esp_usb_jtag_interface,
794 };
const char *const jtag_only[]
Definition: adapter.c:31
int bitq_execute_queue(void)
Definition: bitq.c:206
void bitq_cleanup(void)
Definition: bitq.c:285
void command_print(struct command_invocation *cmd, const char *format,...)
Definition: command.c:473
#define CMD
Use this macro to access the command being handled, rather than accessing the variable directly.
Definition: command.h:140
#define CMD_ARGV
Use this macro to access the arguments for the command being handled, rather than accessing the varia...
Definition: command.h:155
#define ERROR_COMMAND_SYNTAX_ERROR
Definition: command.h:385
#define CMD_ARGC
Use this macro to access the number of arguments for the command being handled, rather than accessing...
Definition: command.h:150
#define COMMAND_PARSE_NUMBER(type, in, out)
parses the string in into out as a type, or prints a command error and passes the error code to the c...
Definition: command.h:425
#define COMMAND_REGISTRATION_DONE
Use this as the last entry in an array of command_registration records.
Definition: command.h:247
@ COMMAND_CONFIG
Definition: command.h:41
@ COMMAND_ANY
Definition: command.h:42
@ COMMAND_EXEC
Definition: command.h:40
static int esp_usb_jtag_send_buf(void)
Definition: esp_usb_jtag.c:284
#define VEND_JTAG_SETIO_TCK
Definition: esp_usb_jtag.c:156
#define JTAG_EUB_DESCR_START_OFF
Definition: esp_usb_jtag.c:119
#define CMD_FLUSH
Definition: esp_usb_jtag.c:162
#define VEND_JTAG_SETIO
Definition: esp_usb_jtag.c:150
#define JTAG_BUILTIN_DESCR_START_OFF
Definition: esp_usb_jtag.c:114
static int esp_usb_jtag_command_add_raw(unsigned int cmd)
Definition: esp_usb_jtag.c:318
static int esp_usb_jtag_quit(void)
Definition: esp_usb_jtag.c:595
static struct esp_usb_jtag * priv
Definition: esp_usb_jtag.c:219
#define VEND_JTAG_SETIO_TMS
Definition: esp_usb_jtag.c:155
#define VEND_DESCR_BUILTIN_JTAG_CAPS
Definition: esp_usb_jtag.c:147
#define CMD_RST(srst)
Definition: esp_usb_jtag.c:161
#define OUT_EP_SZ
Definition: esp_usb_jtag.c:175
static int esp_usb_jtag_khz(int khz, int *divisor)
Definition: esp_usb_jtag.c:611
static int esp_usb_jtag_write_rlestream(unsigned int cmd, int ct)
Definition: esp_usb_jtag.c:338
#define ESP_USB_INTERFACE
Definition: esp_usb_jtag.c:186
static int esp_usb_jtag_flush(void)
Definition: esp_usb_jtag.c:389
static int esp_usb_jtag_out(int tms, int tdi, int tdo_req)
Definition: esp_usb_jtag.c:378
#define VEND_JTAG_GETTDO
Definition: esp_usb_jtag.c:151
static int esp_usb_jtag_init(void)
Definition: esp_usb_jtag.c:475
#define VEND_JTAG_SETDIV
Definition: esp_usb_jtag.c:149
static int esp_usb_jtag_recv_buf(void)
Definition: esp_usb_jtag.c:230
#define JTAG_PROTO_CAPS_DATA_LEN
Definition: esp_usb_jtag.c:144
static int esp_usb_jtag_caps
Definition: esp_usb_jtag.c:223
static int esp_usb_jtag_command_add(unsigned int cmd)
Definition: esp_usb_jtag.c:359
static int esp_usb_jtag_in_rdy(void)
Definition: esp_usb_jtag.c:442
static const struct command_registration esp_usb_jtag_subcommands[]
Definition: esp_usb_jtag.c:727
#define VEND_JTAG_SETIO_SRST
Definition: esp_usb_jtag.c:158
#define VEND_JTAG_SET_CHIPID
Definition: esp_usb_jtag.c:152
static int esp_usb_jtag_reset(int trst, int srst)
Definition: esp_usb_jtag.c:434
static int esp_usb_jtag_speed_div(int divisor, int *khz)
Definition: esp_usb_jtag.c:605
uint8_t div_min[2]
Definition: esp_usb_jtag.c:3
static int esp_usb_vid
Definition: esp_usb_jtag.c:221
static int esp_usb_jtag_speed(int divisor)
Definition: esp_usb_jtag.c:631
#define VEND_JTAG_SETIO_TRST
Definition: esp_usb_jtag.c:157
#define CMD_REP_MAX_REPS
Definition: esp_usb_jtag.c:168
#define USB_CONFIGURATION
Definition: esp_usb_jtag.c:171
#define IN_BUF_SZ
Definition: esp_usb_jtag.c:180
#define VEND_JTAG_SETIO_TDI
Definition: esp_usb_jtag.c:154
struct esp_usb_jtag __attribute__
Definition: armv8.c:804
#define JTAG_PROTO_CAPS_SPEED_APB_TYPE
Definition: esp_usb_jtag.c:145
#define IN_BUF_CT
Definition: esp_usb_jtag.c:184
static const struct command_registration esp_usb_jtag_commands[]
Definition: esp_usb_jtag.c:766
#define OUT_BUF_SZ
Definition: esp_usb_jtag.c:178
static int esp_usb_target_chip_id
Definition: esp_usb_jtag.c:224
#define JTAG_PROTO_CAPS_VER
Definition: esp_usb_jtag.c:107
static struct jtag_interface esp_usb_jtag_interface
Definition: esp_usb_jtag.c:777
COMMAND_HANDLER(esp_usb_jtag_tdo_cmd)
Definition: esp_usb_jtag.c:645
#define CMD_CLK(cap, tdi, tms)
Definition: esp_usb_jtag.c:160
struct adapter_driver esp_usb_adapter_driver
Definition: esp_usb_jtag.c:782
static int esp_usb_jtag_in(void)
Definition: esp_usb_jtag.c:449
static int esp_usb_pid
Definition: esp_usb_jtag.c:222
static struct esp_usb_jtag esp_usb_jtag_priv
Definition: esp_usb_jtag.c:218
static int esp_usb_jtag_sleep(unsigned long us)
Definition: esp_usb_jtag.c:424
#define CMD_REP(r)
Definition: esp_usb_jtag.c:164
#define DEBUG_CAP_TMS_SEQ
Definition: interface.h:189
void jtag_sleep(uint32_t us)
Definition: jtag/core.c:1062
#define ERROR_JTAG_NOT_IMPLEMENTED
Definition: jtag.h:551
int jtag_libusb_bulk_write(struct libusb_device_handle *dev, int ep, char *bytes, int size, int timeout, int *transferred)
int jtag_libusb_control_transfer(struct libusb_device_handle *dev, uint8_t request_type, uint8_t request, uint16_t value, uint16_t index, char *bytes, uint16_t size, unsigned int timeout)
int jtag_libusb_set_configuration(struct libusb_device_handle *devh, int configuration)
void jtag_libusb_close(struct libusb_device_handle *dev)
int jtag_libusb_bulk_read(struct libusb_device_handle *dev, int ep, char *bytes, int size, int timeout, int *transferred)
int jtag_libusb_open(const uint16_t vids[], const uint16_t pids[], struct libusb_device_handle **out, adapter_get_alternate_serial_fn adapter_get_alternate_serial)
int jtag_libusb_choose_interface(struct libusb_device_handle *devh, unsigned int *usb_read_ep, unsigned int *usb_write_ep, int bclass, int subclass, int protocol, int trans_type)
Find the first interface optionally matching class, subclass and protocol and claim it.
#define LIBUSB_TIMEOUT_MS
Definition: libusb_helper.h:26
#define LOG_DEBUG_IO(expr ...)
Definition: log.h:101
#define LOG_WARNING(expr ...)
Definition: log.h:120
#define ERROR_FAIL
Definition: log.h:161
#define LOG_ERROR(expr ...)
Definition: log.h:123
#define LOG_INFO(expr ...)
Definition: log.h:117
#define LOG_DEBUG(expr ...)
Definition: log.h:109
#define ERROR_OK
Definition: log.h:155
#define BIT(nr)
Definition: stm32l4x.h:18
Represents a driver for a debugging interface.
Definition: interface.h:207
const char *const name
The name of the interface driver.
Definition: interface.h:209
int(* in_rdy)(void)
Definition: bitq.h:24
int(* sleep)(unsigned long us)
Definition: bitq.h:18
int(* flush)(void)
Definition: bitq.h:16
int(* in)(void)
Definition: bitq.h:25
int(* reset)(int trst, int srst)
Definition: bitq.h:19
int(* out)(int tms, int tdi, int tdo_req)
Definition: bitq.h:15
const char * name
Definition: command.h:229
const char * usage
a string listing the options and arguments, required or optional
Definition: command.h:235
unsigned int in_buf_size_bits[IN_BUF_CT]
Definition: esp_usb_jtag.c:198
unsigned int out_buf_pos_nibbles
Definition: esp_usb_jtag.c:195
unsigned int read_ep
Definition: esp_usb_jtag.c:202
unsigned int pending_in_bits
Definition: esp_usb_jtag.c:209
unsigned int in_buf_pos_bits
Definition: esp_usb_jtag.c:200
unsigned int prev_cmd
Definition: esp_usb_jtag.c:205
unsigned int hw_in_fifo_len
Definition: esp_usb_jtag.c:211
uint16_t div_min
Definition: esp_usb_jtag.c:192
unsigned int write_ep
Definition: esp_usb_jtag.c:203
unsigned int cur_in_buf_wr
Definition: esp_usb_jtag.c:199
struct bitq_interface bitq_interface
Definition: esp_usb_jtag.c:213
struct libusb_device_handle * usb_device
Definition: esp_usb_jtag.c:190
uint8_t out_buf[OUT_BUF_SZ]
Definition: esp_usb_jtag.c:194
uint16_t div_max
Definition: esp_usb_jtag.c:193
uint32_t base_speed_khz
Definition: esp_usb_jtag.c:191
unsigned int cur_in_buf_rd
Definition: esp_usb_jtag.c:199
uint8_t in_buf[IN_BUF_CT][IN_BUF_SZ]
Definition: esp_usb_jtag.c:197
uint8_t type
Definition: esp_usb_jtag.c:132
uint8_t length
Definition: esp_usb_jtag.c:133
Represents a driver for a debugging interface.
Definition: interface.h:184
unsigned supported
Bit vector listing capabilities exposed by this driver.
Definition: interface.h:188
static uint16_t le_to_h_u16(const uint8_t *buf)
Definition: types.h:122
#define NULL
Definition: usb.h:16
uint8_t cmd
Definition: vdebug.c:1