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 != NULL;
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" PRIx32 " (DA: %" PRId32 ", "
185 "S: %" PRId32 ", EID: 0x%02" PRIx32 ")",
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" PRIx32 ")", 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" PRIx32 ")", 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)
272 int esirisc_jtag_read_hword(struct esirisc_jtag *jtag_info, uint32_t address, uint16_t *data)
274 struct scan_field out_fields[1];
277 out_fields[0].num_bits = 32;
278 out_fields[0].out_value = a;
279 h_u32_to_be(a, address);
280 out_fields[0].in_value = NULL;
282 struct scan_field in_fields[1];
285 in_fields[0].num_bits = 16;
286 in_fields[0].out_value = NULL;
287 in_fields[0].in_value = d;
289 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_HWORD,
290 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
291 if (retval != ERROR_OK)
294 *data = le_to_h_u16(d);
299 int esirisc_jtag_read_word(struct esirisc_jtag *jtag_info, uint32_t address, uint32_t *data)
301 struct scan_field out_fields[1];
304 out_fields[0].num_bits = 32;
305 out_fields[0].out_value = a;
306 h_u32_to_be(a, address);
307 out_fields[0].in_value = NULL;
309 struct scan_field in_fields[1];
312 in_fields[0].num_bits = 32;
313 in_fields[0].out_value = NULL;
314 in_fields[0].in_value = d;
316 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_WORD,
317 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
318 if (retval != ERROR_OK)
321 *data = le_to_h_u32(d);
326 int esirisc_jtag_write_byte(struct esirisc_jtag *jtag_info, uint32_t address, uint8_t data)
328 struct scan_field out_fields[2];
331 out_fields[0].num_bits = 32;
332 out_fields[0].out_value = a;
333 h_u32_to_be(a, address);
334 out_fields[0].in_value = NULL;
336 out_fields[1].num_bits = 8;
337 out_fields[1].out_value = &data;
338 out_fields[1].in_value = NULL;
340 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_BYTE,
341 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
344 int esirisc_jtag_write_hword(struct esirisc_jtag *jtag_info, uint32_t address, uint16_t data)
346 struct scan_field out_fields[2];
349 out_fields[0].num_bits = 32;
350 out_fields[0].out_value = a;
351 h_u32_to_be(a, address);
352 out_fields[0].in_value = NULL;
354 out_fields[1].num_bits = 16;
355 out_fields[1].out_value = d;
356 h_u16_to_be(d, data);
357 out_fields[1].in_value = NULL;
359 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_HWORD,
360 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
363 int esirisc_jtag_write_word(struct esirisc_jtag *jtag_info, uint32_t address, uint32_t data)
365 struct scan_field out_fields[2];
368 out_fields[0].num_bits = 32;
369 out_fields[0].out_value = a;
370 h_u32_to_be(a, address);
371 out_fields[0].in_value = NULL;
373 out_fields[1].num_bits = 32;
374 out_fields[1].out_value = d;
375 h_u32_to_be(d, data);
376 out_fields[1].in_value = NULL;
378 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_WORD,
379 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
382 int esirisc_jtag_read_reg(struct esirisc_jtag *jtag_info, uint8_t reg, uint32_t *data)
384 struct scan_field out_fields[1];
386 out_fields[0].num_bits = 8;
387 out_fields[0].out_value = ®
388 out_fields[0].in_value = NULL;
390 struct scan_field in_fields[1];
393 in_fields[0].num_bits = 32;
394 in_fields[0].out_value = NULL;
395 in_fields[0].in_value = d;
397 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_REG,
398 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
399 if (retval != ERROR_OK)
402 *data = le_to_h_u32(d);
407 int esirisc_jtag_write_reg(struct esirisc_jtag *jtag_info, uint8_t reg, uint32_t data)
409 struct scan_field out_fields[2];
412 out_fields[0].num_bits = 8;
413 out_fields[0].out_value = ®
414 out_fields[0].in_value = NULL;
416 out_fields[1].num_bits = 32;
417 out_fields[1].out_value = d;
418 h_u32_to_be(d, data);
419 out_fields[1].in_value = NULL;
421 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_REG,
422 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
425 int esirisc_jtag_read_csr(struct esirisc_jtag *jtag_info, uint8_t bank, uint8_t csr, uint32_t *data)
427 struct scan_field out_fields[1];
430 out_fields[0].num_bits = 16;
431 out_fields[0].out_value = c;
432 h_u16_to_be(c, (csr << 5) | bank);
433 out_fields[0].in_value = NULL;
435 struct scan_field in_fields[1];
438 in_fields[0].num_bits = 32;
439 in_fields[0].out_value = NULL;
440 in_fields[0].in_value = d;
442 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_CSR,
443 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
444 if (retval != ERROR_OK)
447 *data = le_to_h_u32(d);
452 int esirisc_jtag_write_csr(struct esirisc_jtag *jtag_info, uint8_t bank, uint8_t csr, uint32_t data)
454 struct scan_field out_fields[2];
457 out_fields[0].num_bits = 16;
458 out_fields[0].out_value = c;
459 h_u16_to_be(c, (csr << 5) | bank);
460 out_fields[0].in_value = NULL;
462 out_fields[1].num_bits = 32;
463 out_fields[1].out_value = d;
464 h_u32_to_be(d, data);
465 out_fields[1].in_value = NULL;
467 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_CSR,
468 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
472 * Control commands affect CPU operation; these commands send no data
473 * and return a status byte.
476 static inline int esirisc_jtag_send_ctrl(struct esirisc_jtag *jtag_info, uint8_t command)
478 return esirisc_jtag_send_and_recv(jtag_info, command, 0, NULL, 0, NULL);
481 int esirisc_jtag_enable_debug(struct esirisc_jtag *jtag_info)
483 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_ENABLE_DEBUG);
486 int esirisc_jtag_disable_debug(struct esirisc_jtag *jtag_info)
488 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_DISABLE_DEBUG);
491 int esirisc_jtag_assert_reset(struct esirisc_jtag *jtag_info)
493 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_ASSERT_RESET);
496 int esirisc_jtag_deassert_reset(struct esirisc_jtag *jtag_info)
498 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_DEASSERT_RESET);
501 int esirisc_jtag_break(struct esirisc_jtag *jtag_info)
503 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_BREAK);
506 int esirisc_jtag_continue(struct esirisc_jtag *jtag_info)
508 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_CONTINUE);
511 int esirisc_jtag_flush_caches(struct esirisc_jtag *jtag_info)
513 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_FLUSH_CACHES);