1 // SPDX-License-Identifier: GPL-2.0-or-later
6 * Copyright (C) 2013 Franck Jullien, <elec4fun@gmail.com>
8 * See file CREDITS for list of people who contributed to this
16 #include <jtag/interface.h>
17 #ifdef HAVE_ARPA_INET_H
18 #include <arpa/inet.h>
22 #include <netinet/tcp.h>
25 #include "helper/replacements.h"
27 #define NO_TAP_SHIFT 0
30 #define DEFAULT_SERVER_ADDRESS "127.0.0.1"
31 #define DEFAULT_SERVER_PORT 5555
33 #define XFERT_MAX_SIZE 512
37 #define CMD_SCAN_CHAIN 2
38 #define CMD_SCAN_CHAIN_FLIP_TMS 3
39 #define CMD_STOP_SIMU 4
41 /* jtag_vpi server port and address to connect to */
42 static int server_port
= DEFAULT_SERVER_PORT
;
43 static char *server_address
;
45 /* Send CMD_STOP_SIMU to server when OpenOCD exits? */
46 static bool stop_sim_on_exit
;
49 static struct sockaddr_in serv_addr
;
51 /* One jtag_vpi "packet" as sent over a TCP channel. */
55 unsigned char cmd_buf
[4];
57 unsigned char buffer_out
[XFERT_MAX_SIZE
];
58 unsigned char buffer_in
[XFERT_MAX_SIZE
];
61 unsigned char length_buf
[4];
65 unsigned char nb_bits_buf
[4];
69 static char *jtag_vpi_cmd_to_str(int cmd_num
)
77 return "CMD_SCAN_CHAIN";
78 case CMD_SCAN_CHAIN_FLIP_TMS
:
79 return "CMD_SCAN_CHAIN_FLIP_TMS";
81 return "CMD_STOP_SIMU";
87 static int jtag_vpi_send_cmd(struct vpi_cmd
*vpi
)
91 /* Optional low-level JTAG debug */
92 if (LOG_LEVEL_IS(LOG_LVL_DEBUG_IO
)) {
93 if (vpi
->nb_bits
> 0) {
94 /* command with a non-empty data payload */
95 char *char_buf
= buf_to_hex_str(vpi
->buffer_out
,
96 (vpi
->nb_bits
> DEBUG_JTAG_IOZ
)
99 LOG_DEBUG_IO("sending JTAG VPI cmd: cmd=%s, "
100 "length=%" PRIu32
", "
101 "nb_bits=%" PRIu32
", "
103 jtag_vpi_cmd_to_str(vpi
->cmd
),
107 (vpi
->nb_bits
> DEBUG_JTAG_IOZ
) ? "(...)" : "");
110 /* command without data payload */
111 LOG_DEBUG_IO("sending JTAG VPI cmd: cmd=%s, "
112 "length=%" PRIu32
", "
114 jtag_vpi_cmd_to_str(vpi
->cmd
),
120 /* Use little endian when transmitting/receiving jtag_vpi cmds.
121 The choice of little endian goes against usual networking conventions
122 but is intentional to remain compatible with most older OpenOCD builds
123 (i.e. builds on little-endian platforms). */
124 h_u32_to_le(vpi
->cmd_buf
, vpi
->cmd
);
125 h_u32_to_le(vpi
->length_buf
, vpi
->length
);
126 h_u32_to_le(vpi
->nb_bits_buf
, vpi
->nb_bits
);
129 retval
= write_socket(sockfd
, vpi
, sizeof(struct vpi_cmd
));
132 /* Account for the case when socket write is interrupted. */
134 int wsa_err
= WSAGetLastError();
135 if (wsa_err
== WSAEINTR
)
141 /* Otherwise this is an error using the socket, most likely fatal
142 for the connection. B*/
143 log_socket_error("jtag_vpi xmit");
144 /* TODO: Clean way how adapter drivers can report fatal errors
145 to upper layers of OpenOCD and let it perform an orderly shutdown? */
147 } else if (retval
< (int)sizeof(struct vpi_cmd
)) {
148 /* This means we could not send all data, which is most likely fatal
149 for the jtag_vpi connection (the underlying TCP connection likely not
151 LOG_ERROR("jtag_vpi: Could not send all data through jtag_vpi connection.");
155 /* Otherwise the packet has been sent successfully. */
159 static int jtag_vpi_receive_cmd(struct vpi_cmd
*vpi
)
161 unsigned int bytes_buffered
= 0;
162 while (bytes_buffered
< sizeof(struct vpi_cmd
)) {
163 int bytes_to_receive
= sizeof(struct vpi_cmd
) - bytes_buffered
;
164 int retval
= read_socket(sockfd
, ((char *)vpi
) + bytes_buffered
, bytes_to_receive
);
167 int wsa_err
= WSAGetLastError();
168 if (wsa_err
== WSAEINTR
) {
169 /* socket read interrupted by WSACancelBlockingCall() */
173 if (errno
== EINTR
) {
174 /* socket read interrupted by a signal */
178 /* Otherwise, this is an error when accessing the socket. */
179 log_socket_error("jtag_vpi recv");
181 } else if (retval
== 0) {
182 /* Connection closed by the other side */
183 LOG_ERROR("Connection prematurely closed by jtag_vpi server.");
186 /* Otherwise, we have successfully received some data */
187 bytes_buffered
+= retval
;
190 /* Use little endian when transmitting/receiving jtag_vpi cmds. */
191 vpi
->cmd
= le_to_h_u32(vpi
->cmd_buf
);
192 vpi
->length
= le_to_h_u32(vpi
->length_buf
);
193 vpi
->nb_bits
= le_to_h_u32(vpi
->nb_bits_buf
);
199 * jtag_vpi_reset - ask to reset the JTAG device
200 * @param trst 1 if TRST is to be asserted
201 * @param srst 1 if SRST is to be asserted
203 static int jtag_vpi_reset(int trst
, int srst
)
206 memset(&vpi
, 0, sizeof(struct vpi_cmd
));
210 return jtag_vpi_send_cmd(&vpi
);
214 * jtag_vpi_tms_seq - ask a TMS sequence transition to JTAG
215 * @param bits TMS bits to be written (bit0, bit1 .. bitN)
216 * @param nb_bits number of TMS bits (between 1 and 8)
218 * Write a series of TMS transitions, where each transition consists in :
219 * - writing out TCK=0, TMS=\<new_state>, TDI=\<???>
220 * - writing out TCK=1, TMS=\<new_state>, TDI=\<???> which triggers the transition
221 * The function ensures that at the end of the sequence, the clock (TCK) is put
224 static int jtag_vpi_tms_seq(const uint8_t *bits
, int nb_bits
)
229 memset(&vpi
, 0, sizeof(struct vpi_cmd
));
230 nb_bytes
= DIV_ROUND_UP(nb_bits
, 8);
232 vpi
.cmd
= CMD_TMS_SEQ
;
233 memcpy(vpi
.buffer_out
, bits
, nb_bytes
);
234 vpi
.length
= nb_bytes
;
235 vpi
.nb_bits
= nb_bits
;
237 return jtag_vpi_send_cmd(&vpi
);
241 * jtag_vpi_path_move - ask a TMS sequence transition to JTAG
242 * @param cmd path transition
244 * Write a series of TMS transitions, where each transition consists in :
245 * - writing out TCK=0, TMS=\<new_state>, TDI=\<???>
246 * - writing out TCK=1, TMS=\<new_state>, TDI=\<???> which triggers the transition
247 * The function ensures that at the end of the sequence, the clock (TCK) is put
251 static int jtag_vpi_path_move(struct pathmove_command
*cmd
)
253 uint8_t trans
[DIV_ROUND_UP(cmd
->num_states
, 8)];
255 memset(trans
, 0, DIV_ROUND_UP(cmd
->num_states
, 8));
257 for (unsigned int i
= 0; i
< cmd
->num_states
; i
++) {
258 if (tap_state_transition(tap_get_state(), true) == cmd
->path
[i
])
259 buf_set_u32(trans
, i
, 1, 1);
260 tap_set_state(cmd
->path
[i
]);
263 return jtag_vpi_tms_seq(trans
, cmd
->num_states
);
267 * jtag_vpi_tms - ask a tms command
268 * @param cmd tms command
270 static int jtag_vpi_tms(struct tms_command
*cmd
)
272 return jtag_vpi_tms_seq(cmd
->bits
, cmd
->num_bits
);
275 static int jtag_vpi_state_move(tap_state_t state
)
277 if (tap_get_state() == state
)
280 uint8_t tms_scan
= tap_get_tms_path(tap_get_state(), state
);
281 int tms_len
= tap_get_tms_path_len(tap_get_state(), state
);
283 int retval
= jtag_vpi_tms_seq(&tms_scan
, tms_len
);
284 if (retval
!= ERROR_OK
)
287 tap_set_state(state
);
292 static int jtag_vpi_queue_tdi_xfer(uint8_t *bits
, int nb_bits
, int tap_shift
)
295 int nb_bytes
= DIV_ROUND_UP(nb_bits
, 8);
297 memset(&vpi
, 0, sizeof(struct vpi_cmd
));
299 vpi
.cmd
= tap_shift
? CMD_SCAN_CHAIN_FLIP_TMS
: CMD_SCAN_CHAIN
;
302 memcpy(vpi
.buffer_out
, bits
, nb_bytes
);
304 memset(vpi
.buffer_out
, 0xff, nb_bytes
);
306 vpi
.length
= nb_bytes
;
307 vpi
.nb_bits
= nb_bits
;
309 int retval
= jtag_vpi_send_cmd(&vpi
);
310 if (retval
!= ERROR_OK
)
313 retval
= jtag_vpi_receive_cmd(&vpi
);
314 if (retval
!= ERROR_OK
)
317 /* Optional low-level JTAG debug */
318 if (LOG_LEVEL_IS(LOG_LVL_DEBUG_IO
)) {
319 char *char_buf
= buf_to_hex_str(vpi
.buffer_in
,
320 (nb_bits
> DEBUG_JTAG_IOZ
) ? DEBUG_JTAG_IOZ
: nb_bits
);
321 LOG_DEBUG_IO("recvd JTAG VPI data: nb_bits=%d, buf_in=0x%s%s",
322 nb_bits
, char_buf
, (nb_bits
> DEBUG_JTAG_IOZ
) ? "(...)" : "");
327 memcpy(bits
, vpi
.buffer_in
, nb_bytes
);
333 * jtag_vpi_queue_tdi - short description
334 * @param bits bits to be queued on TDI (or NULL if 0 are to be queued)
335 * @param nb_bits number of bits
338 static int jtag_vpi_queue_tdi(uint8_t *bits
, int nb_bits
, int tap_shift
)
340 int nb_xfer
= DIV_ROUND_UP(nb_bits
, XFERT_MAX_SIZE
* 8);
345 retval
= jtag_vpi_queue_tdi_xfer(bits
, nb_bits
, tap_shift
);
346 if (retval
!= ERROR_OK
)
349 retval
= jtag_vpi_queue_tdi_xfer(bits
, XFERT_MAX_SIZE
* 8, NO_TAP_SHIFT
);
350 if (retval
!= ERROR_OK
)
352 nb_bits
-= XFERT_MAX_SIZE
* 8;
354 bits
+= XFERT_MAX_SIZE
;
364 * jtag_vpi_clock_tms - clock a TMS transition
365 * @param tms the TMS to be sent
367 * Triggers a TMS transition (ie. one JTAG TAP state move).
369 static int jtag_vpi_clock_tms(int tms
)
371 const uint8_t tms_0
= 0;
372 const uint8_t tms_1
= 1;
374 return jtag_vpi_tms_seq(tms
? &tms_1
: &tms_0
, 1);
378 * jtag_vpi_scan - launches a DR-scan or IR-scan
379 * @param cmd the command to launch
381 * Launch a JTAG IR-scan or DR-scan
383 * Returns ERROR_OK if OK, ERROR_xxx if a read/write error occurred.
385 static int jtag_vpi_scan(struct scan_command
*cmd
)
389 int retval
= ERROR_OK
;
391 scan_bits
= jtag_build_buffer(cmd
, &buf
);
394 retval
= jtag_vpi_state_move(TAP_IRSHIFT
);
395 if (retval
!= ERROR_OK
)
398 retval
= jtag_vpi_state_move(TAP_DRSHIFT
);
399 if (retval
!= ERROR_OK
)
403 if (cmd
->end_state
== TAP_DRSHIFT
) {
404 retval
= jtag_vpi_queue_tdi(buf
, scan_bits
, NO_TAP_SHIFT
);
405 if (retval
!= ERROR_OK
)
408 retval
= jtag_vpi_queue_tdi(buf
, scan_bits
, TAP_SHIFT
);
409 if (retval
!= ERROR_OK
)
413 if (cmd
->end_state
!= TAP_DRSHIFT
) {
415 * As our JTAG is in an unstable state (IREXIT1 or DREXIT1), move it
416 * forward to a stable IRPAUSE or DRPAUSE.
418 retval
= jtag_vpi_clock_tms(0);
419 if (retval
!= ERROR_OK
)
423 tap_set_state(TAP_IRPAUSE
);
425 tap_set_state(TAP_DRPAUSE
);
428 retval
= jtag_read_buffer(buf
, cmd
);
429 if (retval
!= ERROR_OK
)
434 if (cmd
->end_state
!= TAP_DRSHIFT
) {
435 retval
= jtag_vpi_state_move(cmd
->end_state
);
436 if (retval
!= ERROR_OK
)
443 static int jtag_vpi_runtest(unsigned int num_cycles
, tap_state_t state
)
447 retval
= jtag_vpi_state_move(TAP_IDLE
);
448 if (retval
!= ERROR_OK
)
451 retval
= jtag_vpi_queue_tdi(NULL
, num_cycles
, NO_TAP_SHIFT
);
452 if (retval
!= ERROR_OK
)
455 return jtag_vpi_state_move(state
);
458 static int jtag_vpi_stableclocks(unsigned int num_cycles
)
461 unsigned int cycles_remain
= num_cycles
;
464 const unsigned int cycles_one_batch
= sizeof(tms_bits
) * 8;
466 /* use TMS=1 in TAP RESET state, TMS=0 in all other stable states */
467 memset(&tms_bits
, (tap_get_state() == TAP_RESET
) ? 0xff : 0x00, sizeof(tms_bits
));
469 /* send the TMS bits */
470 while (cycles_remain
> 0) {
471 nb_bits
= (cycles_remain
< cycles_one_batch
) ? cycles_remain
: cycles_one_batch
;
472 retval
= jtag_vpi_tms_seq(tms_bits
, nb_bits
);
473 if (retval
!= ERROR_OK
)
475 cycles_remain
-= nb_bits
;
481 static int jtag_vpi_execute_queue(struct jtag_command
*cmd_queue
)
483 struct jtag_command
*cmd
;
484 int retval
= ERROR_OK
;
486 for (cmd
= cmd_queue
; retval
== ERROR_OK
&& cmd
;
490 retval
= jtag_vpi_reset(cmd
->cmd
.reset
->trst
, cmd
->cmd
.reset
->srst
);
493 retval
= jtag_vpi_runtest(cmd
->cmd
.runtest
->num_cycles
,
494 cmd
->cmd
.runtest
->end_state
);
496 case JTAG_STABLECLOCKS
:
497 retval
= jtag_vpi_stableclocks(cmd
->cmd
.stableclocks
->num_cycles
);
500 retval
= jtag_vpi_state_move(cmd
->cmd
.statemove
->end_state
);
503 retval
= jtag_vpi_path_move(cmd
->cmd
.pathmove
);
506 retval
= jtag_vpi_tms(cmd
->cmd
.tms
);
509 jtag_sleep(cmd
->cmd
.sleep
->us
);
512 retval
= jtag_vpi_scan(cmd
->cmd
.scan
);
515 LOG_ERROR("BUG: unknown JTAG command type 0x%X",
525 static int jtag_vpi_init(void)
529 sockfd
= socket(AF_INET
, SOCK_STREAM
, 0);
531 LOG_ERROR("jtag_vpi: Could not create client socket");
535 memset(&serv_addr
, 0, sizeof(serv_addr
));
537 serv_addr
.sin_family
= AF_INET
;
538 serv_addr
.sin_port
= htons(server_port
);
541 server_address
= strdup(DEFAULT_SERVER_ADDRESS
);
543 serv_addr
.sin_addr
.s_addr
= inet_addr(server_address
);
545 if (serv_addr
.sin_addr
.s_addr
== INADDR_NONE
) {
546 LOG_ERROR("jtag_vpi: inet_addr error occurred");
550 if (connect(sockfd
, (struct sockaddr
*)&serv_addr
, sizeof(serv_addr
)) < 0) {
552 LOG_ERROR("jtag_vpi: Can't connect to %s : %u", server_address
, server_port
);
553 return ERROR_COMMAND_CLOSE_CONNECTION
;
556 if (serv_addr
.sin_addr
.s_addr
== htonl(INADDR_LOOPBACK
)) {
557 /* This increases performance dramatically for local
558 * connections, which is the most likely arrangement
559 * for a VPI connection. */
560 setsockopt(sockfd
, IPPROTO_TCP
, TCP_NODELAY
, (char *)&flag
, sizeof(int));
563 LOG_INFO("jtag_vpi: Connection to %s : %u successful", server_address
, server_port
);
568 static int jtag_vpi_stop_simulation(void)
571 memset(&cmd
, 0, sizeof(struct vpi_cmd
));
574 cmd
.cmd
= CMD_STOP_SIMU
;
575 return jtag_vpi_send_cmd(&cmd
);
578 static int jtag_vpi_quit(void)
580 if (stop_sim_on_exit
) {
581 if (jtag_vpi_stop_simulation() != ERROR_OK
)
582 LOG_WARNING("jtag_vpi: failed to send \"stop simulation\" command");
584 if (close_socket(sockfd
) != 0) {
585 LOG_WARNING("jtag_vpi: could not close jtag_vpi client socket");
586 log_socket_error("jtag_vpi");
588 free(server_address
);
592 COMMAND_HANDLER(jtag_vpi_set_port
)
595 return ERROR_COMMAND_SYNTAX_ERROR
;
597 COMMAND_PARSE_NUMBER(int, CMD_ARGV
[0], server_port
);
598 LOG_INFO("jtag_vpi: server port set to %u", server_port
);
603 COMMAND_HANDLER(jtag_vpi_set_address
)
607 return ERROR_COMMAND_SYNTAX_ERROR
;
609 free(server_address
);
610 server_address
= strdup(CMD_ARGV
[0]);
611 LOG_INFO("jtag_vpi: server address set to %s", server_address
);
616 COMMAND_HANDLER(jtag_vpi_stop_sim_on_exit_handler
)
619 return ERROR_COMMAND_SYNTAX_ERROR
;
621 COMMAND_PARSE_ON_OFF(CMD_ARGV
[0], stop_sim_on_exit
);
625 static const struct command_registration jtag_vpi_subcommand_handlers
[] = {
628 .handler
= &jtag_vpi_set_port
,
629 .mode
= COMMAND_CONFIG
,
630 .help
= "set the TCP port number of the jtag_vpi server (default: 5555)",
631 .usage
= "tcp_port_num",
634 .name
= "set_address",
635 .handler
= &jtag_vpi_set_address
,
636 .mode
= COMMAND_CONFIG
,
637 .help
= "set the IP address of the jtag_vpi server (default: 127.0.0.1)",
638 .usage
= "ipv4_addr",
641 .name
= "stop_sim_on_exit",
642 .handler
= &jtag_vpi_stop_sim_on_exit_handler
,
643 .mode
= COMMAND_CONFIG
,
644 .help
= "Configure if simulation stop command shall be sent "
645 "before OpenOCD exits (default: off)",
648 COMMAND_REGISTRATION_DONE
651 static const struct command_registration jtag_vpi_command_handlers
[] = {
655 .help
= "perform jtag_vpi management",
656 .chain
= jtag_vpi_subcommand_handlers
,
659 COMMAND_REGISTRATION_DONE
662 static struct jtag_interface jtag_vpi_interface
= {
663 .supported
= DEBUG_CAP_TMS_SEQ
,
664 .execute_queue
= jtag_vpi_execute_queue
,
667 struct adapter_driver jtag_vpi_adapter_driver
= {
669 .transports
= jtag_only
,
670 .commands
= jtag_vpi_command_handlers
,
672 .init
= jtag_vpi_init
,
673 .quit
= jtag_vpi_quit
,
675 .jtag_ops
= &jtag_vpi_interface
,