1 /***************************************************************************
2 * Copyright (C) 2018 by Square, Inc. *
3 * Steven Stallion <stallion@squareup.com> *
4 * James Zhao <hjz@squareup.com> *
6 * This program is free software; you can redistribute it and/or modify *
7 * it under the terms of the GNU General Public License as published by *
8 * the Free Software Foundation; either version 2 of the License, or *
9 * (at your option) any later version. *
11 * This program is distributed in the hope that it will be useful, *
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
14 * GNU General Public License for more details. *
16 * You should have received a copy of the GNU General Public License *
17 * along with this program. If not, see <http://www.gnu.org/licenses/>. *
18 ***************************************************************************/
24 #include <helper/binarybuffer.h>
25 #include <helper/log.h>
26 #include <helper/types.h>
27 #include <jtag/jtag.h>
28 #include <jtag/commands.h>
29 #include <jtag/interface.h>
31 #include "esirisc_jtag.h"
33 static void esirisc_jtag_set_instr(struct esirisc_jtag *jtag_info, uint32_t new_instr)
35 struct jtag_tap *tap = jtag_info->tap;
37 if (buf_get_u32(tap->cur_instr, 0, tap->ir_length) != new_instr) {
38 struct scan_field field;
41 field.num_bits = tap->ir_length;
43 buf_set_u32(t, 0, field.num_bits, new_instr);
44 field.in_value = NULL;
46 jtag_add_ir_scan(tap, &field, TAP_IDLE);
51 * The data register is latched every 8 bits while in the Shift-DR state
52 * (Update-DR is not supported). This necessitates prepending padding
53 * bits to ensure data is aligned when multiple TAPs are present.
55 static int esirisc_jtag_get_padding(void)
58 int bypass_devices = 0;
60 for (struct jtag_tap *tap = jtag_tap_next_enabled(NULL); tap;
61 tap = jtag_tap_next_enabled(tap))
65 int num_bits = bypass_devices % 8;
67 padding = 8 - num_bits;
72 static int esirisc_jtag_count_bits(int num_fields, struct scan_field *fields)
76 for (int i = 0; i < num_fields; ++i)
77 bit_count += fields[i].num_bits;
83 * Data received from the target will be byte-stuffed if it contains
84 * either the pad byte (0xAA) or stuffing marker (0x55). Buffers should
85 * be sized twice the expected length to account for stuffing overhead.
87 static void esirisc_jtag_unstuff(uint8_t *data, size_t len)
95 if (*r == STUFF_MARKER) {
96 r++; /* skip stuffing marker */
98 *w++ = *r++ ^ STUFF_MARKER;
105 * The eSi-Debug protocol defines a byte-oriented command/response
106 * channel that operates over serial or JTAG. While not strictly
107 * required, separate DR scans are used for sending and receiving data.
108 * This allows the TAP to recover gracefully if the byte stream is
109 * corrupted at the expense of sending additional padding bits.
112 static int esirisc_jtag_send(struct esirisc_jtag *jtag_info, uint8_t command,
113 int num_out_fields, struct scan_field *out_fields)
115 int num_fields = 2 + num_out_fields;
116 struct scan_field *fields = cmd_queue_alloc(num_fields * sizeof(struct scan_field));
118 esirisc_jtag_set_instr(jtag_info, INSTR_DEBUG);
120 fields[0].num_bits = esirisc_jtag_get_padding();
121 fields[0].out_value = NULL;
122 fields[0].in_value = NULL;
124 fields[1].num_bits = 8;
125 fields[1].out_value = &command;
126 fields[1].in_value = NULL;
128 /* append command data */
129 for (int i = 0; i < num_out_fields; ++i)
130 jtag_scan_field_clone(&fields[2+i], &out_fields[i]);
132 jtag_add_dr_scan(jtag_info->tap, num_fields, fields, TAP_IDLE);
134 return jtag_execute_queue();
137 static int esirisc_jtag_recv(struct esirisc_jtag *jtag_info,
138 int num_in_fields, struct scan_field *in_fields)
140 int num_in_bits = esirisc_jtag_count_bits(num_in_fields, in_fields);
141 int num_in_bytes = DIV_ROUND_UP(num_in_bits, 8);
143 struct scan_field fields[3];
144 uint8_t r[num_in_bytes * 2];
146 esirisc_jtag_set_instr(jtag_info, INSTR_DEBUG);
148 fields[0].num_bits = esirisc_jtag_get_padding() + 1;
149 fields[0].out_value = NULL;
150 fields[0].in_value = NULL;
152 fields[1].num_bits = 8;
153 fields[1].out_value = NULL;
154 fields[1].in_value = &jtag_info->status;
156 fields[2].num_bits = num_in_bits * 2;
157 fields[2].out_value = NULL;
158 fields[2].in_value = r;
160 jtag_add_dr_scan(jtag_info->tap, ARRAY_SIZE(fields), fields, TAP_IDLE);
162 int retval = jtag_execute_queue();
163 if (retval != ERROR_OK)
166 /* unstuff response data and write back to caller */
167 if (num_in_fields > 0) {
168 esirisc_jtag_unstuff(r, ARRAY_SIZE(r));
171 for (int i = 0; i < num_in_fields; ++i) {
172 buf_set_buf(r, bit_count, in_fields[i].in_value, 0, in_fields[i].num_bits);
173 bit_count += in_fields[i].num_bits;
180 static int esirisc_jtag_check_status(struct esirisc_jtag *jtag_info)
182 uint8_t eid = esirisc_jtag_get_eid(jtag_info);
183 if (eid != EID_NONE) {
184 LOG_ERROR("esirisc_jtag: bad status: 0x%02" PRIx8 " (DA: %" PRId32 ", "
185 "S: %" PRId32 ", EID: 0x%02" PRIx8 ")",
186 jtag_info->status, esirisc_jtag_is_debug_active(jtag_info),
187 esirisc_jtag_is_stopped(jtag_info), eid);
194 static int esirisc_jtag_send_and_recv(struct esirisc_jtag *jtag_info, uint8_t command,
195 int num_out_fields, struct scan_field *out_fields,
196 int num_in_fields, struct scan_field *in_fields)
200 jtag_info->status = 0; /* clear status */
202 retval = esirisc_jtag_send(jtag_info, command, num_out_fields, out_fields);
203 if (retval != ERROR_OK) {
204 LOG_ERROR("esirisc_jtag: send failed (command: 0x%02" PRIx8 ")", command);
208 retval = esirisc_jtag_recv(jtag_info, num_in_fields, in_fields);
209 if (retval != ERROR_OK) {
210 LOG_ERROR("esirisc_jtag: recv failed (command: 0x%02" PRIx8 ")", command);
214 return esirisc_jtag_check_status(jtag_info);
218 * Status is automatically updated after each command completes;
219 * these functions make each field available to the caller.
222 bool esirisc_jtag_is_debug_active(struct esirisc_jtag *jtag_info)
224 return !!(jtag_info->status & 1<<7); /* DA */
227 bool esirisc_jtag_is_stopped(struct esirisc_jtag *jtag_info)
229 return !!(jtag_info->status & 1<<6); /* S */
232 uint8_t esirisc_jtag_get_eid(struct esirisc_jtag *jtag_info)
234 return jtag_info->status & 0x3f; /* EID */
238 * Most commands manipulate target data (eg. memory and registers); each
239 * command returns a status byte that indicates success. Commands must
240 * transmit multibyte values in big-endian order, however response
241 * values are in little-endian order. Target endianness does not have an
242 * effect on this ordering.
245 int esirisc_jtag_read_byte(struct esirisc_jtag *jtag_info, uint32_t address, uint8_t *data)
247 struct scan_field out_fields[1];
250 out_fields[0].num_bits = 32;
251 out_fields[0].out_value = a;
252 h_u32_to_be(a, address);
253 out_fields[0].in_value = NULL;
255 struct scan_field in_fields[1];
258 in_fields[0].num_bits = 8;
259 in_fields[0].out_value = NULL;
260 in_fields[0].in_value = d;
262 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_BYTE,
263 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
264 if (retval != ERROR_OK)
268 LOG_DEBUG("address: 0x%" PRIx32 ", data: 0x%" PRIx8, address, *data);
273 int esirisc_jtag_read_hword(struct esirisc_jtag *jtag_info, uint32_t address, uint16_t *data)
275 struct scan_field out_fields[1];
278 out_fields[0].num_bits = 32;
279 out_fields[0].out_value = a;
280 h_u32_to_be(a, address);
281 out_fields[0].in_value = NULL;
283 struct scan_field in_fields[1];
286 in_fields[0].num_bits = 16;
287 in_fields[0].out_value = NULL;
288 in_fields[0].in_value = d;
290 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_HWORD,
291 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
292 if (retval != ERROR_OK)
295 *data = le_to_h_u16(d);
296 LOG_DEBUG("address: 0x%" PRIx32 ", data: 0x%" PRIx16, address, *data);
301 int esirisc_jtag_read_word(struct esirisc_jtag *jtag_info, uint32_t address, uint32_t *data)
303 struct scan_field out_fields[1];
306 out_fields[0].num_bits = 32;
307 out_fields[0].out_value = a;
308 h_u32_to_be(a, address);
309 out_fields[0].in_value = NULL;
311 struct scan_field in_fields[1];
314 in_fields[0].num_bits = 32;
315 in_fields[0].out_value = NULL;
316 in_fields[0].in_value = d;
318 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_WORD,
319 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
320 if (retval != ERROR_OK)
323 *data = le_to_h_u32(d);
324 LOG_DEBUG("address: 0x%" PRIx32 ", data: 0x%" PRIx32, address, *data);
329 int esirisc_jtag_write_byte(struct esirisc_jtag *jtag_info, uint32_t address, uint8_t data)
331 struct scan_field out_fields[2];
334 LOG_DEBUG("address: 0x%" PRIx32 ", data: 0x%" PRIx8, address, data);
336 out_fields[0].num_bits = 32;
337 out_fields[0].out_value = a;
338 h_u32_to_be(a, address);
339 out_fields[0].in_value = NULL;
341 out_fields[1].num_bits = 8;
342 out_fields[1].out_value = &data;
343 out_fields[1].in_value = NULL;
345 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_BYTE,
346 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
349 int esirisc_jtag_write_hword(struct esirisc_jtag *jtag_info, uint32_t address, uint16_t data)
351 struct scan_field out_fields[2];
354 LOG_DEBUG("address: 0x%" PRIx32 ", data: 0x%" PRIx16, address, data);
356 out_fields[0].num_bits = 32;
357 out_fields[0].out_value = a;
358 h_u32_to_be(a, address);
359 out_fields[0].in_value = NULL;
361 out_fields[1].num_bits = 16;
362 out_fields[1].out_value = d;
363 h_u16_to_be(d, data);
364 out_fields[1].in_value = NULL;
366 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_HWORD,
367 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
370 int esirisc_jtag_write_word(struct esirisc_jtag *jtag_info, uint32_t address, uint32_t data)
372 struct scan_field out_fields[2];
375 LOG_DEBUG("address: 0x%" PRIx32 ", data: 0x%" PRIx32, address, data);
377 out_fields[0].num_bits = 32;
378 out_fields[0].out_value = a;
379 h_u32_to_be(a, address);
380 out_fields[0].in_value = NULL;
382 out_fields[1].num_bits = 32;
383 out_fields[1].out_value = d;
384 h_u32_to_be(d, data);
385 out_fields[1].in_value = NULL;
387 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_WORD,
388 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
391 int esirisc_jtag_read_reg(struct esirisc_jtag *jtag_info, uint8_t reg, uint32_t *data)
393 struct scan_field out_fields[1];
395 out_fields[0].num_bits = 8;
396 out_fields[0].out_value = ®
397 out_fields[0].in_value = NULL;
399 struct scan_field in_fields[1];
402 in_fields[0].num_bits = 32;
403 in_fields[0].out_value = NULL;
404 in_fields[0].in_value = d;
406 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_REG,
407 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
408 if (retval != ERROR_OK)
411 *data = le_to_h_u32(d);
412 LOG_DEBUG("register: 0x%" PRIx8 ", data: 0x%" PRIx32, reg, *data);
417 int esirisc_jtag_write_reg(struct esirisc_jtag *jtag_info, uint8_t reg, uint32_t data)
419 struct scan_field out_fields[2];
422 LOG_DEBUG("register: 0x%" PRIx8 ", data: 0x%" PRIx32, reg, data);
424 out_fields[0].num_bits = 8;
425 out_fields[0].out_value = ®
426 out_fields[0].in_value = NULL;
428 out_fields[1].num_bits = 32;
429 out_fields[1].out_value = d;
430 h_u32_to_be(d, data);
431 out_fields[1].in_value = NULL;
433 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_REG,
434 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
437 int esirisc_jtag_read_csr(struct esirisc_jtag *jtag_info, uint8_t bank, uint8_t csr, uint32_t *data)
439 struct scan_field out_fields[1];
442 out_fields[0].num_bits = 16;
443 out_fields[0].out_value = c;
444 h_u16_to_be(c, (csr << 5) | bank);
445 out_fields[0].in_value = NULL;
447 struct scan_field in_fields[1];
450 in_fields[0].num_bits = 32;
451 in_fields[0].out_value = NULL;
452 in_fields[0].in_value = d;
454 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_CSR,
455 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
456 if (retval != ERROR_OK)
459 *data = le_to_h_u32(d);
460 LOG_DEBUG("bank: 0x%" PRIx8 ", csr: 0x%" PRIx8 ", data: 0x%" PRIx32, bank, csr, *data);
465 int esirisc_jtag_write_csr(struct esirisc_jtag *jtag_info, uint8_t bank, uint8_t csr, uint32_t data)
467 struct scan_field out_fields[2];
470 LOG_DEBUG("bank: 0x%" PRIx8 ", csr: 0x%" PRIx8 ", data: 0x%" PRIx32, bank, csr, data);
472 out_fields[0].num_bits = 16;
473 out_fields[0].out_value = c;
474 h_u16_to_be(c, (csr << 5) | bank);
475 out_fields[0].in_value = NULL;
477 out_fields[1].num_bits = 32;
478 out_fields[1].out_value = d;
479 h_u32_to_be(d, data);
480 out_fields[1].in_value = NULL;
482 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_CSR,
483 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
487 * Control commands affect CPU operation; these commands send no data
488 * and return a status byte.
491 static inline int esirisc_jtag_send_ctrl(struct esirisc_jtag *jtag_info, uint8_t command)
493 return esirisc_jtag_send_and_recv(jtag_info, command, 0, NULL, 0, NULL);
496 int esirisc_jtag_enable_debug(struct esirisc_jtag *jtag_info)
498 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_ENABLE_DEBUG);
501 int esirisc_jtag_disable_debug(struct esirisc_jtag *jtag_info)
503 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_DISABLE_DEBUG);
506 int esirisc_jtag_assert_reset(struct esirisc_jtag *jtag_info)
508 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_ASSERT_RESET);
511 int esirisc_jtag_deassert_reset(struct esirisc_jtag *jtag_info)
513 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_DEASSERT_RESET);
516 int esirisc_jtag_break(struct esirisc_jtag *jtag_info)
518 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_BREAK);
521 int esirisc_jtag_continue(struct esirisc_jtag *jtag_info)
523 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_CONTINUE);
526 int esirisc_jtag_flush_caches(struct esirisc_jtag *jtag_info)
528 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_FLUSH_CACHES);