1 /* SPDX-License-Identifier: GPL-2.0-or-later */
3 /***************************************************************************
4 * Copyright (C) 2018 by Square, Inc. *
5 * Steven Stallion <stallion@squareup.com> *
6 * James Zhao <hjz@squareup.com> *
7 ***************************************************************************/
13 #include <helper/binarybuffer.h>
14 #include <helper/log.h>
15 #include <helper/types.h>
16 #include <jtag/jtag.h>
17 #include <jtag/commands.h>
18 #include <jtag/interface.h>
20 #include "esirisc_jtag.h"
22 static void esirisc_jtag_set_instr(struct esirisc_jtag *jtag_info, uint32_t new_instr)
24 struct jtag_tap *tap = jtag_info->tap;
26 if (buf_get_u32(tap->cur_instr, 0, tap->ir_length) != new_instr) {
27 struct scan_field field;
30 field.num_bits = tap->ir_length;
32 buf_set_u32(t, 0, field.num_bits, new_instr);
33 field.in_value = NULL;
35 jtag_add_ir_scan(tap, &field, TAP_IDLE);
40 * The data register is latched every 8 bits while in the Shift-DR state
41 * (Update-DR is not supported). This necessitates prepending padding
42 * bits to ensure data is aligned when multiple TAPs are present.
44 static int esirisc_jtag_get_padding(void)
47 int bypass_devices = 0;
49 for (struct jtag_tap *tap = jtag_tap_next_enabled(NULL); tap;
50 tap = jtag_tap_next_enabled(tap))
54 int num_bits = bypass_devices % 8;
56 padding = 8 - num_bits;
61 static int esirisc_jtag_count_bits(int num_fields, struct scan_field *fields)
65 for (int i = 0; i < num_fields; ++i)
66 bit_count += fields[i].num_bits;
72 * Data received from the target will be byte-stuffed if it contains
73 * either the pad byte (0xAA) or stuffing marker (0x55). Buffers should
74 * be sized twice the expected length to account for stuffing overhead.
76 static void esirisc_jtag_unstuff(uint8_t *data, size_t len)
84 if (*r == STUFF_MARKER) {
85 r++; /* skip stuffing marker */
87 *w++ = *r++ ^ STUFF_MARKER;
94 * The eSi-Debug protocol defines a byte-oriented command/response
95 * channel that operates over serial or JTAG. While not strictly
96 * required, separate DR scans are used for sending and receiving data.
97 * This allows the TAP to recover gracefully if the byte stream is
98 * corrupted at the expense of sending additional padding bits.
101 static int esirisc_jtag_send(struct esirisc_jtag *jtag_info, uint8_t command,
102 int num_out_fields, struct scan_field *out_fields)
104 int num_fields = 2 + num_out_fields;
105 struct scan_field *fields = cmd_queue_alloc(num_fields * sizeof(struct scan_field));
107 esirisc_jtag_set_instr(jtag_info, INSTR_DEBUG);
109 fields[0].num_bits = esirisc_jtag_get_padding();
110 fields[0].out_value = NULL;
111 fields[0].in_value = NULL;
113 fields[1].num_bits = 8;
114 fields[1].out_value = &command;
115 fields[1].in_value = NULL;
117 /* append command data */
118 for (int i = 0; i < num_out_fields; ++i)
119 jtag_scan_field_clone(&fields[2+i], &out_fields[i]);
121 jtag_add_dr_scan(jtag_info->tap, num_fields, fields, TAP_IDLE);
123 return jtag_execute_queue();
126 static int esirisc_jtag_recv(struct esirisc_jtag *jtag_info,
127 int num_in_fields, struct scan_field *in_fields)
129 int num_in_bits = esirisc_jtag_count_bits(num_in_fields, in_fields);
130 int num_in_bytes = DIV_ROUND_UP(num_in_bits, 8);
132 struct scan_field fields[3];
133 uint8_t r[num_in_bytes * 2];
135 esirisc_jtag_set_instr(jtag_info, INSTR_DEBUG);
137 fields[0].num_bits = esirisc_jtag_get_padding() + 1;
138 fields[0].out_value = NULL;
139 fields[0].in_value = NULL;
141 fields[1].num_bits = 8;
142 fields[1].out_value = NULL;
143 fields[1].in_value = &jtag_info->status;
145 fields[2].num_bits = num_in_bits * 2;
146 fields[2].out_value = NULL;
147 fields[2].in_value = r;
149 jtag_add_dr_scan(jtag_info->tap, ARRAY_SIZE(fields), fields, TAP_IDLE);
151 int retval = jtag_execute_queue();
152 if (retval != ERROR_OK)
155 /* unstuff response data and write back to caller */
156 if (num_in_fields > 0) {
157 esirisc_jtag_unstuff(r, ARRAY_SIZE(r));
160 for (int i = 0; i < num_in_fields; ++i) {
161 buf_set_buf(r, bit_count, in_fields[i].in_value, 0, in_fields[i].num_bits);
162 bit_count += in_fields[i].num_bits;
169 static int esirisc_jtag_check_status(struct esirisc_jtag *jtag_info)
171 uint8_t eid = esirisc_jtag_get_eid(jtag_info);
172 if (eid != EID_NONE) {
173 LOG_ERROR("esirisc_jtag: bad status: 0x%02" PRIx8 " (DA: %" PRId32 ", "
174 "S: %" PRId32 ", EID: 0x%02" PRIx8 ")",
175 jtag_info->status, esirisc_jtag_is_debug_active(jtag_info),
176 esirisc_jtag_is_stopped(jtag_info), eid);
183 static int esirisc_jtag_send_and_recv(struct esirisc_jtag *jtag_info, uint8_t command,
184 int num_out_fields, struct scan_field *out_fields,
185 int num_in_fields, struct scan_field *in_fields)
189 jtag_info->status = 0; /* clear status */
191 retval = esirisc_jtag_send(jtag_info, command, num_out_fields, out_fields);
192 if (retval != ERROR_OK) {
193 LOG_ERROR("esirisc_jtag: send failed (command: 0x%02" PRIx8 ")", command);
197 retval = esirisc_jtag_recv(jtag_info, num_in_fields, in_fields);
198 if (retval != ERROR_OK) {
199 LOG_ERROR("esirisc_jtag: recv failed (command: 0x%02" PRIx8 ")", command);
203 return esirisc_jtag_check_status(jtag_info);
207 * Status is automatically updated after each command completes;
208 * these functions make each field available to the caller.
211 bool esirisc_jtag_is_debug_active(struct esirisc_jtag *jtag_info)
213 return !!(jtag_info->status & 1<<7); /* DA */
216 bool esirisc_jtag_is_stopped(struct esirisc_jtag *jtag_info)
218 return !!(jtag_info->status & 1<<6); /* S */
221 uint8_t esirisc_jtag_get_eid(struct esirisc_jtag *jtag_info)
223 return jtag_info->status & 0x3f; /* EID */
227 * Most commands manipulate target data (eg. memory and registers); each
228 * command returns a status byte that indicates success. Commands must
229 * transmit multibyte values in big-endian order, however response
230 * values are in little-endian order. Target endianness does not have an
231 * effect on this ordering.
234 int esirisc_jtag_read_byte(struct esirisc_jtag *jtag_info, uint32_t address, uint8_t *data)
236 struct scan_field out_fields[1];
239 out_fields[0].num_bits = 32;
240 out_fields[0].out_value = a;
241 h_u32_to_be(a, address);
242 out_fields[0].in_value = NULL;
244 struct scan_field in_fields[1];
247 in_fields[0].num_bits = 8;
248 in_fields[0].out_value = NULL;
249 in_fields[0].in_value = d;
251 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_BYTE,
252 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
253 if (retval != ERROR_OK)
257 LOG_DEBUG("address: 0x%" PRIx32 ", data: 0x%" PRIx8, address, *data);
262 int esirisc_jtag_read_hword(struct esirisc_jtag *jtag_info, uint32_t address, uint16_t *data)
264 struct scan_field out_fields[1];
267 out_fields[0].num_bits = 32;
268 out_fields[0].out_value = a;
269 h_u32_to_be(a, address);
270 out_fields[0].in_value = NULL;
272 struct scan_field in_fields[1];
275 in_fields[0].num_bits = 16;
276 in_fields[0].out_value = NULL;
277 in_fields[0].in_value = d;
279 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_HWORD,
280 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
281 if (retval != ERROR_OK)
284 *data = le_to_h_u16(d);
285 LOG_DEBUG("address: 0x%" PRIx32 ", data: 0x%" PRIx16, address, *data);
290 int esirisc_jtag_read_word(struct esirisc_jtag *jtag_info, uint32_t address, uint32_t *data)
292 struct scan_field out_fields[1];
295 out_fields[0].num_bits = 32;
296 out_fields[0].out_value = a;
297 h_u32_to_be(a, address);
298 out_fields[0].in_value = NULL;
300 struct scan_field in_fields[1];
303 in_fields[0].num_bits = 32;
304 in_fields[0].out_value = NULL;
305 in_fields[0].in_value = d;
307 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_WORD,
308 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
309 if (retval != ERROR_OK)
312 *data = le_to_h_u32(d);
313 LOG_DEBUG("address: 0x%" PRIx32 ", data: 0x%" PRIx32, address, *data);
318 int esirisc_jtag_write_byte(struct esirisc_jtag *jtag_info, uint32_t address, uint8_t data)
320 struct scan_field out_fields[2];
323 LOG_DEBUG("address: 0x%" PRIx32 ", data: 0x%" PRIx8, address, data);
325 out_fields[0].num_bits = 32;
326 out_fields[0].out_value = a;
327 h_u32_to_be(a, address);
328 out_fields[0].in_value = NULL;
330 out_fields[1].num_bits = 8;
331 out_fields[1].out_value = &data;
332 out_fields[1].in_value = NULL;
334 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_BYTE,
335 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
338 int esirisc_jtag_write_hword(struct esirisc_jtag *jtag_info, uint32_t address, uint16_t data)
340 struct scan_field out_fields[2];
343 LOG_DEBUG("address: 0x%" PRIx32 ", data: 0x%" PRIx16, address, data);
345 out_fields[0].num_bits = 32;
346 out_fields[0].out_value = a;
347 h_u32_to_be(a, address);
348 out_fields[0].in_value = NULL;
350 out_fields[1].num_bits = 16;
351 out_fields[1].out_value = d;
352 h_u16_to_be(d, data);
353 out_fields[1].in_value = NULL;
355 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_HWORD,
356 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
359 int esirisc_jtag_write_word(struct esirisc_jtag *jtag_info, uint32_t address, uint32_t data)
361 struct scan_field out_fields[2];
364 LOG_DEBUG("address: 0x%" PRIx32 ", data: 0x%" PRIx32, address, data);
366 out_fields[0].num_bits = 32;
367 out_fields[0].out_value = a;
368 h_u32_to_be(a, address);
369 out_fields[0].in_value = NULL;
371 out_fields[1].num_bits = 32;
372 out_fields[1].out_value = d;
373 h_u32_to_be(d, data);
374 out_fields[1].in_value = NULL;
376 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_WORD,
377 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
380 int esirisc_jtag_read_reg(struct esirisc_jtag *jtag_info, uint8_t reg, uint32_t *data)
382 struct scan_field out_fields[1];
384 out_fields[0].num_bits = 8;
385 out_fields[0].out_value = ®
386 out_fields[0].in_value = NULL;
388 struct scan_field in_fields[1];
391 in_fields[0].num_bits = 32;
392 in_fields[0].out_value = NULL;
393 in_fields[0].in_value = d;
395 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_REG,
396 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
397 if (retval != ERROR_OK)
400 *data = le_to_h_u32(d);
401 LOG_DEBUG("register: 0x%" PRIx8 ", data: 0x%" PRIx32, reg, *data);
406 int esirisc_jtag_write_reg(struct esirisc_jtag *jtag_info, uint8_t reg, uint32_t data)
408 struct scan_field out_fields[2];
411 LOG_DEBUG("register: 0x%" PRIx8 ", data: 0x%" PRIx32, reg, data);
413 out_fields[0].num_bits = 8;
414 out_fields[0].out_value = ®
415 out_fields[0].in_value = NULL;
417 out_fields[1].num_bits = 32;
418 out_fields[1].out_value = d;
419 h_u32_to_be(d, data);
420 out_fields[1].in_value = NULL;
422 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_REG,
423 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
426 int esirisc_jtag_read_csr(struct esirisc_jtag *jtag_info, uint8_t bank, uint8_t csr, uint32_t *data)
428 struct scan_field out_fields[1];
431 out_fields[0].num_bits = 16;
432 out_fields[0].out_value = c;
433 h_u16_to_be(c, (csr << 5) | bank);
434 out_fields[0].in_value = NULL;
436 struct scan_field in_fields[1];
439 in_fields[0].num_bits = 32;
440 in_fields[0].out_value = NULL;
441 in_fields[0].in_value = d;
443 int retval = esirisc_jtag_send_and_recv(jtag_info, DEBUG_READ_CSR,
444 ARRAY_SIZE(out_fields), out_fields, ARRAY_SIZE(in_fields), in_fields);
445 if (retval != ERROR_OK)
448 *data = le_to_h_u32(d);
449 LOG_DEBUG("bank: 0x%" PRIx8 ", csr: 0x%" PRIx8 ", data: 0x%" PRIx32, bank, csr, *data);
454 int esirisc_jtag_write_csr(struct esirisc_jtag *jtag_info, uint8_t bank, uint8_t csr, uint32_t data)
456 struct scan_field out_fields[2];
459 LOG_DEBUG("bank: 0x%" PRIx8 ", csr: 0x%" PRIx8 ", data: 0x%" PRIx32, bank, csr, data);
461 out_fields[0].num_bits = 16;
462 out_fields[0].out_value = c;
463 h_u16_to_be(c, (csr << 5) | bank);
464 out_fields[0].in_value = NULL;
466 out_fields[1].num_bits = 32;
467 out_fields[1].out_value = d;
468 h_u32_to_be(d, data);
469 out_fields[1].in_value = NULL;
471 return esirisc_jtag_send_and_recv(jtag_info, DEBUG_WRITE_CSR,
472 ARRAY_SIZE(out_fields), out_fields, 0, NULL);
476 * Control commands affect CPU operation; these commands send no data
477 * and return a status byte.
480 static inline int esirisc_jtag_send_ctrl(struct esirisc_jtag *jtag_info, uint8_t command)
482 return esirisc_jtag_send_and_recv(jtag_info, command, 0, NULL, 0, NULL);
485 int esirisc_jtag_enable_debug(struct esirisc_jtag *jtag_info)
487 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_ENABLE_DEBUG);
490 int esirisc_jtag_disable_debug(struct esirisc_jtag *jtag_info)
492 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_DISABLE_DEBUG);
495 int esirisc_jtag_assert_reset(struct esirisc_jtag *jtag_info)
497 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_ASSERT_RESET);
500 int esirisc_jtag_deassert_reset(struct esirisc_jtag *jtag_info)
502 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_DEASSERT_RESET);
505 int esirisc_jtag_break(struct esirisc_jtag *jtag_info)
507 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_BREAK);
510 int esirisc_jtag_continue(struct esirisc_jtag *jtag_info)
512 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_CONTINUE);
515 int esirisc_jtag_flush_caches(struct esirisc_jtag *jtag_info)
517 return esirisc_jtag_send_ctrl(jtag_info, DEBUG_FLUSH_CACHES);