1 /* Remote target communications for serial-line targets in custom GDB protocol
2 Copyright 1988, 1991, 1992, 1993 Free Software Foundation, Inc.
4 This file is part of GDB.
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, write to the Free Software
18 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */
20 /* Remote communication protocol.
22 A debug packet whose contents are <data>
23 is encapsulated for transmission in the form:
25 $ <data> # CSUM1 CSUM2
27 <data> must be ASCII alphanumeric and cannot include characters
30 CSUM1 and CSUM2 are ascii hex representation of an 8-bit
31 checksum of <data>, the most significant nibble is sent first.
32 the hex digits 0-9,a-f are used.
34 Receiver responds with:
36 + - if CSUM is correct and ready for next packet
37 - - if CSUM is incorrect
40 All values are encoded in ascii hex digits.
45 reply XX....X Each byte of register data
46 is described by two hex digits.
47 Registers are in the internal order
48 for GDB, and the bytes in a register
49 are in the same order the machine uses.
52 write regs GXX..XX Each byte of register data
53 is described by two hex digits.
57 read mem mAA..AA,LLLL AA..AA is address, LLLL is length.
58 reply XX..XX XX..XX is mem contents
61 write mem MAA..AA,LLLL:XX..XX
63 LLLL is number of bytes,
68 cont cAA..AA AA..AA is address to resume
70 resume at same address.
72 step sAA..AA AA..AA is address to resume
74 resume at same address.
76 last signal ? Reply the current reason for stopping.
77 This is the same reply as is generated
78 for step or cont : SAA where AA is the
81 There is no immediate reply to step or cont.
82 The reply comes when the machine stops.
83 It is SAA AA is the "signal number"
85 or... TAAn...:r...;n:r...;n...:r...;
87 n... = register number
88 r... = register contents
102 #include "terminal.h"
105 #if !defined(DONT_USE_REMOTE)
107 #include <sys/types.h>
113 /* Prototypes for local functions */
116 remote_write_bytes
PARAMS ((CORE_ADDR
, char *, int));
119 remote_read_bytes
PARAMS ((CORE_ADDR
, char *, int));
122 remote_files_info
PARAMS ((struct target_ops
*));
125 remote_xfer_memory
PARAMS ((CORE_ADDR
, char *, int, int, struct target_ops
*));
128 remote_prepare_to_store
PARAMS ((void));
131 remote_fetch_registers
PARAMS ((int));
134 remote_resume
PARAMS ((int, int));
137 remote_start_remote
PARAMS ((char *));
140 remote_open
PARAMS ((char *, int));
143 remote_close
PARAMS ((int));
146 remote_store_registers
PARAMS ((int));
149 getpkt
PARAMS ((char *, int));
152 putpkt
PARAMS ((char *));
155 remote_send
PARAMS ((char *));
158 readchar
PARAMS ((void));
161 remote_wait
PARAMS ((WAITTYPE
*));
164 tohex
PARAMS ((int));
167 fromhex
PARAMS ((int));
170 remote_detach
PARAMS ((char *, int));
172 extern struct target_ops remote_ops
; /* Forward decl */
174 static int kiodebug
= 0;
175 /* This was 5 seconds, which is a long time to sit and wait.
176 Unless this is going though some terminal server or multiplexer or
177 other form of hairy serial connection, I would think 2 seconds would
179 static int timeout
= 2;
185 /* Descriptor for I/O to remote machine. Initialize it to -1 so that
186 remote_open knows that we don't have a file open when the program
188 serial_t remote_desc
= NULL
;
192 /* Maximum number of bytes to read/write at once. The value here
193 is chosen to fill up a packet (the headers account for the 32). */
194 #define MAXBUFBYTES ((PBUFSIZ-32)/2)
196 /* Round up PBUFSIZ to hold all the registers, at least. */
197 #if REGISTER_BYTES > MAXBUFBYTES
199 #define PBUFSIZ (REGISTER_BYTES * 2 + 32)
202 /* Clean up connection to a remote debugger. */
206 remote_close (quitting
)
210 SERIAL_CLOSE (remote_desc
);
214 /* Stub for catch_errors. */
217 remote_start_remote (dummy
)
220 /* Ack any packet which the remote side has already sent. */
221 SERIAL_WRITE (remote_desc
, "+\r", 2);
222 putpkt ("?"); /* initiate a query from remote machine */
224 start_remote (); /* Initialize gdb process mechanisms */
228 /* Open a connection to a remote debugger.
229 NAME is the filename used for communication. */
232 remote_open (name
, from_tty
)
238 "To open a remote debug connection, you need to specify what serial\n\
239 device is attached to the remote system (e.g. /dev/ttya).");
241 target_preopen (from_tty
);
243 unpush_target (&remote_ops
);
249 remote_desc
= SERIAL_OPEN (name
);
251 perror_with_name (name
);
257 if (sscanf (baud_rate
, "%d", &rate
) == 1)
258 if (SERIAL_SETBAUDRATE (remote_desc
, rate
))
260 SERIAL_CLOSE (remote_desc
);
261 perror_with_name (name
);
265 SERIAL_RAW (remote_desc
);
269 puts_filtered ("Remote debugging using ");
270 puts_filtered (name
);
271 puts_filtered ("\n");
273 push_target (&remote_ops
); /* Switch to using remote target now */
275 /* Start the remote connection; if error (0), discard this target. */
276 immediate_quit
++; /* Allow user to interrupt it */
277 if (!catch_errors (remote_start_remote
, (char *)0,
278 "Couldn't establish connection to remote target\n", RETURN_MASK_ALL
))
283 takes a program previously attached to and detaches it.
284 We better not have left any breakpoints
285 in the program or it'll die when it hits one.
286 Close the open connection to the remote debugger.
287 Use this when you want to detach and do something else
291 remote_detach (args
, from_tty
)
296 error ("Argument given to \"detach\" when remotely debugging.");
300 puts_filtered ("Ending remote debugging.\n");
303 /* Convert hex digit A to a number. */
309 if (a
>= '0' && a
<= '9')
311 else if (a
>= 'a' && a
<= 'f')
314 error ("Reply contains invalid hex digit");
318 /* Convert number NIB to a hex digit. */
330 /* Tell the remote machine to resume. */
333 remote_resume (step
, siggnal
)
341 target_terminal_ours_for_output ();
342 printf_filtered ("Can't send signals to a remote system. ");
343 name
= strsigno (siggnal
);
345 printf_filtered (name
);
347 printf_filtered ("Signal %d", siggnal
);
348 printf_filtered (" not sent.\n");
349 target_terminal_inferior ();
356 strcpy (buf
, step
? "s": "c");
361 static void remote_interrupt_twice
PARAMS ((int));
362 static void (*ofunc
)();
364 /* Send ^C to target to halt it. Target will respond, and send us a
367 void remote_interrupt(signo
)
370 /* If this doesn't work, try more severe steps. */
371 signal (signo
, remote_interrupt_twice
);
374 printf ("remote_interrupt called\n");
376 SERIAL_WRITE (remote_desc
, "\003", 1); /* Send a ^C */
379 /* The user typed ^C twice. */
381 remote_interrupt_twice (signo
)
384 signal (signo
, ofunc
);
386 target_terminal_ours ();
387 if (query ("Interrupted while waiting for the program.\n\
388 Give up (and stop debugging it)? "))
390 target_mourn_inferior ();
391 return_to_top_level (RETURN_QUIT
);
395 signal (signo
, remote_interrupt
);
396 target_terminal_inferior ();
400 /* Wait until the remote machine stops, then return,
401 storing status in STATUS just as `wait' would.
402 Returns "pid" (though it's not clear what, if anything, that
403 means in the case of this target). */
409 unsigned char buf
[PBUFSIZ
];
413 char regs
[MAX_REGISTER_RAW_SIZE
];
415 WSETEXIT ((*status
), 0);
417 ofunc
= (void (*)()) signal (SIGINT
, remote_interrupt
);
418 getpkt ((char *) buf
, 1);
419 signal (SIGINT
, ofunc
);
422 error ("Remote failure reply: %s", buf
);
425 /* Expedited reply, containing Signal, {regno, reg} repeat */
426 /* format is: 'Tssn...:r...;n...:r...;n...:r...;#cc', where
428 n... = register number
429 r... = register contents
432 p
= &buf
[3]; /* after Txx */
436 regno
= strtol (p
, &p
, 16); /* Read the register number */
439 || regno
>= NUM_REGS
)
440 error ("Remote sent bad register number %s", buf
);
442 for (i
= 0; i
< REGISTER_RAW_SIZE (regno
); i
++)
444 if (p
[0] == 0 || p
[1] == 0)
445 error ("Remote reply is too short: %s", buf
);
446 regs
[i
] = fromhex (p
[0]) * 16 + fromhex (p
[1]);
451 error("Remote register badly formatted: %s", buf
);
453 supply_register (regno
, regs
);
456 else if (buf
[0] != 'S')
457 error ("Invalid remote reply: %s", buf
);
459 WSETSTOP ((*status
), (((fromhex (buf
[1])) << 4) + (fromhex (buf
[2]))));
464 /* Read the remote registers into the block REGS. */
465 /* Currently we just read all the registers, so we don't use regno. */
468 remote_fetch_registers (regno
)
474 char regs
[REGISTER_BYTES
];
479 /* Reply describes registers byte by byte, each byte encoded as two
480 hex characters. Suck them all up, then supply them to the
481 register cacheing/storage mechanism. */
484 for (i
= 0; i
< REGISTER_BYTES
; i
++)
486 if (p
[0] == 0 || p
[1] == 0)
487 error ("Remote reply is too short: %s", buf
);
488 regs
[i
] = fromhex (p
[0]) * 16 + fromhex (p
[1]);
491 for (i
= 0; i
< NUM_REGS
; i
++)
492 supply_register (i
, ®s
[REGISTER_BYTE(i
)]);
495 /* Prepare to store registers. Since we send them all, we have to
496 read out the ones we don't want to change first. */
499 remote_prepare_to_store ()
501 /* Make sure the entire registers array is valid. */
502 read_register_bytes (0, (char *)NULL
, REGISTER_BYTES
);
505 /* Store the remote registers from the contents of the block REGISTERS.
506 FIXME, eventually just store one register if that's all that is needed. */
510 remote_store_registers (regno
)
519 /* Command describes registers byte by byte,
520 each byte encoded as two hex characters. */
523 for (i
= 0; i
< REGISTER_BYTES
; i
++)
525 *p
++ = tohex ((registers
[i
] >> 4) & 0xf);
526 *p
++ = tohex (registers
[i
] & 0xf);
534 /* Read a word from remote address ADDR and return it.
535 This goes through the data cache. */
538 remote_fetch_word (addr
)
543 extern CORE_ADDR text_start
, text_end
;
545 if (addr
>= text_start
&& addr
< text_end
)
548 xfer_core_file (addr
, &buffer
, sizeof (int));
552 return dcache_fetch (addr
);
555 /* Write a word WORD into remote address ADDR.
556 This goes through the data cache. */
559 remote_store_word (addr
, word
)
563 dcache_poke (addr
, word
);
567 /* Write memory data directly to the remote machine.
568 This does not inform the data cache; the data cache uses this.
569 MEMADDR is the address in the remote memory space.
570 MYADDR is the address of the buffer in our space.
571 LEN is the number of bytes. */
574 remote_write_bytes (memaddr
, myaddr
, len
)
583 if (len
> PBUFSIZ
/ 2 - 20)
586 sprintf (buf
, "M%x,%x:", memaddr
, len
);
588 /* We send target system values byte by byte, in increasing byte addresses,
589 each byte encoded as two hex characters. */
591 p
= buf
+ strlen (buf
);
592 for (i
= 0; i
< len
; i
++)
594 *p
++ = tohex ((myaddr
[i
] >> 4) & 0xf);
595 *p
++ = tohex (myaddr
[i
] & 0xf);
602 /* Read memory data directly from the remote machine.
603 This does not use the data cache; the data cache uses this.
604 MEMADDR is the address in the remote memory space.
605 MYADDR is the address of the buffer in our space.
606 LEN is the number of bytes. */
609 remote_read_bytes (memaddr
, myaddr
, len
)
618 if (len
> PBUFSIZ
/ 2 - 1)
621 sprintf (buf
, "m%x,%x", memaddr
, len
);
624 /* Reply describes memory byte by byte,
625 each byte encoded as two hex characters. */
628 for (i
= 0; i
< len
; i
++)
630 if (p
[0] == 0 || p
[1] == 0)
631 error ("Remote reply is too short: %s", buf
);
632 myaddr
[i
] = fromhex (p
[0]) * 16 + fromhex (p
[1]);
637 /* Read or write LEN bytes from inferior memory at MEMADDR, transferring
638 to or from debugger address MYADDR. Write to inferior if SHOULD_WRITE is
639 nonzero. Returns length of data written or read; 0 for error. */
643 remote_xfer_memory(memaddr
, myaddr
, len
, should_write
, target
)
648 struct target_ops
*target
; /* ignored */
654 if (len
> MAXBUFBYTES
)
655 xfersize
= MAXBUFBYTES
;
660 remote_write_bytes(memaddr
, myaddr
, xfersize
);
662 remote_read_bytes (memaddr
, myaddr
, xfersize
);
667 return origlen
; /* no error possible */
671 remote_files_info (ignore
)
672 struct target_ops
*ignore
;
674 puts_filtered ("Debugging a target over a serial line.\n");
677 /* Stuff for dealing with the packets which are part of this protocol.
678 See comment at top of file for details. */
680 /* Read a single character from the remote end, masking it down to 7 bits. */
687 ch
= SERIAL_READCHAR (remote_desc
, timeout
);
695 /* Send the command in BUF to the remote machine,
696 and read the reply into BUF.
697 Report an error if we get an error reply. */
708 error ("Remote failure reply: %s", buf
);
711 /* Send a packet to the remote machine, with error checking.
712 The data of the packet is in BUF. */
719 unsigned char csum
= 0;
721 int cnt
= strlen (buf
);
725 /* Copy the packet into buffer BUF2, encapsulating it
726 and giving it a checksum. */
728 if (cnt
> sizeof(buf2
) - 5) /* Prosanity check */
734 for (i
= 0; i
< cnt
; i
++)
740 *p
++ = tohex ((csum
>> 4) & 0xf);
741 *p
++ = tohex (csum
& 0xf);
743 /* Send it over and over until we get a positive ack. */
750 printf ("Sending packet: %s...", buf2
); fflush(stdout
);
752 if (SERIAL_WRITE (remote_desc
, buf2
, p
- buf2
))
753 perror_with_name ("putpkt: write failed");
755 /* read until either a timeout occurs (-2) or '+' is read */
767 break; /* Retransmit buffer */
769 perror_with_name ("putpkt: couldn't read ACK");
771 error ("putpkt: EOF while trying to read ACK");
774 printf ("%02X %c ", ch
&0xFF, ch
);
777 break; /* Here to retransmit */
782 /* Read a packet from the remote machine, with error checking,
783 and store it in BUF. BUF is expected to be of size PBUFSIZ.
784 If FOREVER, wait forever rather than timing out; this is used
785 while the target is executing user code. */
788 getpkt (buf
, forever
)
795 unsigned char c1
, c2
;
797 #define MAX_RETRIES 10
801 /* This can loop forever if the remote side sends us characters
802 continuously, but if it pauses, we'll get a zero from readchar
803 because of timeout. Then we'll count that as a retry. */
806 if (c
> 0 && c
!= '$')
809 if (c
== SERIAL_TIMEOUT
)
813 if (++retries
>= MAX_RETRIES
)
814 if (kiodebug
) puts_filtered ("Timed out.\n");
819 error ("Remote connection closed");
820 if (c
== SERIAL_ERROR
)
821 perror_with_name ("Remote communication error");
823 /* Force csum to be zero here because of possible error retry. */
830 if (c
== SERIAL_TIMEOUT
)
833 puts_filtered ("Timeout in mid-packet, retrying\n");
834 goto whole
; /* Start a new packet, count retries */
839 puts_filtered ("Saw new packet start in middle of old one\n");
840 goto whole
; /* Start a new packet, count retries */
844 if (bp
>= buf
+PBUFSIZ
-1)
847 puts_filtered ("Remote packet too long: ");
849 puts_filtered ("\n");
857 c1
= fromhex (readchar ());
858 c2
= fromhex (readchar ());
859 if ((csum
& 0xff) == (c1
<< 4) + c2
)
861 printf_filtered ("Bad checksum, sentsum=0x%x, csum=0x%x, buf=",
862 (c1
<< 4) + c2
, csum
& 0xff);
864 puts_filtered ("\n");
866 /* Try the whole thing again. */
868 if (++retries
< MAX_RETRIES
)
870 SERIAL_WRITE (remote_desc
, "-", 1);
874 printf ("Ignoring packet error, continuing...\n");
881 SERIAL_WRITE (remote_desc
, "+", 1);
884 fprintf (stderr
,"Packet received: %s\n", buf
);
887 /* The data cache leads to incorrect results because it doesn't know about
888 volatile variables, thus making it impossible to debug functions which
889 use hardware registers. Therefore it is #if 0'd out. Effect on
890 performance is some, for backtraces of functions with a few
891 arguments each. For functions with many arguments, the stack
892 frames don't fit in the cache blocks, which makes the cache less
893 helpful. Disabling the cache is a big performance win for fetching
894 large structures, because the cache code fetched data in 16-byte
897 /* The data cache records all the data read from the remote machine
898 since the last time it stopped.
900 Each cache block holds 16 bytes of data
901 starting at a multiple-of-16 address. */
903 #define DCACHE_SIZE 64 /* Number of cache blocks */
905 struct dcache_block
{
906 struct dcache_block
*next
, *last
;
907 unsigned int addr
; /* Address for which data is recorded. */
911 struct dcache_block dcache_free
, dcache_valid
;
913 /* Free all the data cache blocks, thus discarding all cached data. */
918 register struct dcache_block
*db
;
920 while ((db
= dcache_valid
.next
) != &dcache_valid
)
923 insque (db
, &dcache_free
);
928 * If addr is present in the dcache, return the address of the block
932 struct dcache_block
*
935 register struct dcache_block
*db
;
940 /* Search all cache blocks for one that is at this address. */
941 db
= dcache_valid
.next
;
942 while (db
!= &dcache_valid
)
944 if ((addr
& 0xfffffff0) == db
->addr
)
951 /* Return the int data at address ADDR in dcache block DC. */
954 dcache_value (db
, addr
)
955 struct dcache_block
*db
;
960 return (db
->data
[(addr
>>2)&3]);
963 /* Get a free cache block, put it on the valid list,
964 and return its address. The caller should store into the block
965 the address and data that it describes. */
967 struct dcache_block
*
970 register struct dcache_block
*db
;
972 if ((db
= dcache_free
.next
) == &dcache_free
)
973 /* If we can't get one from the free list, take last valid */
974 db
= dcache_valid
.last
;
977 insque (db
, &dcache_valid
);
981 /* Return the contents of the word at address ADDR in the remote machine,
982 using the data cache. */
988 register struct dcache_block
*db
;
990 db
= dcache_hit (addr
);
993 db
= dcache_alloc ();
994 remote_read_bytes (addr
& ~0xf, db
->data
, 16);
995 db
->addr
= addr
& ~0xf;
997 return (dcache_value (db
, addr
));
1000 /* Write the word at ADDR both in the data cache and in the remote machine. */
1002 dcache_poke (addr
, data
)
1006 register struct dcache_block
*db
;
1008 /* First make sure the word is IN the cache. DB is its cache block. */
1009 db
= dcache_hit (addr
);
1012 db
= dcache_alloc ();
1013 remote_read_bytes (addr
& ~0xf, db
->data
, 16);
1014 db
->addr
= addr
& ~0xf;
1017 /* Modify the word in the cache. */
1018 db
->data
[(addr
>>2)&3] = data
;
1020 /* Send the changed word. */
1021 remote_write_bytes (addr
, &data
, 4);
1024 /* Initialize the data cache. */
1029 register struct dcache_block
*db
;
1031 db
= (struct dcache_block
*) xmalloc (sizeof (struct dcache_block
) *
1033 dcache_free
.next
= dcache_free
.last
= &dcache_free
;
1034 dcache_valid
.next
= dcache_valid
.last
= &dcache_valid
;
1035 for (i
=0;i
<DCACHE_SIZE
;i
++,db
++)
1036 insque (db
, &dcache_free
);
1044 /* Don't wait for it to die. I'm not really sure it matters whether
1045 we do or not. For the existing stubs, kill is a noop. */
1046 target_mourn_inferior ();
1052 unpush_target (&remote_ops
);
1053 generic_mourn_inferior ();
1056 /* Define the target subroutine names */
1058 struct target_ops remote_ops
= {
1059 "remote", /* to_shortname */
1060 "Remote serial target in gdb-specific protocol", /* to_longname */
1061 "Use a remote computer via a serial line, using a gdb-specific protocol.\n\
1062 Specify the serial device it is connected to (e.g. /dev/ttya).", /* to_doc */
1063 remote_open
, /* to_open */
1064 remote_close
, /* to_close */
1065 NULL
, /* to_attach */
1066 remote_detach
, /* to_detach */
1067 remote_resume
, /* to_resume */
1068 remote_wait
, /* to_wait */
1069 remote_fetch_registers
, /* to_fetch_registers */
1070 remote_store_registers
, /* to_store_registers */
1071 remote_prepare_to_store
, /* to_prepare_to_store */
1072 remote_xfer_memory
, /* to_xfer_memory */
1073 remote_files_info
, /* to_files_info */
1074 NULL
, /* to_insert_breakpoint */
1075 NULL
, /* to_remove_breakpoint */
1076 NULL
, /* to_terminal_init */
1077 NULL
, /* to_terminal_inferior */
1078 NULL
, /* to_terminal_ours_for_output */
1079 NULL
, /* to_terminal_ours */
1080 NULL
, /* to_terminal_info */
1081 remote_kill
, /* to_kill */
1082 generic_load
, /* to_load */
1083 NULL
, /* to_lookup_symbol */
1084 NULL
, /* to_create_inferior */
1085 remote_mourn
, /* to_mourn_inferior */
1087 0, /* to_notice_signals */
1088 process_stratum
, /* to_stratum */
1090 1, /* to_has_all_memory */
1091 1, /* to_has_memory */
1092 1, /* to_has_stack */
1093 1, /* to_has_registers */
1094 1, /* to_has_execution */
1095 NULL
, /* sections */
1096 NULL
, /* sections_end */
1097 OPS_MAGIC
/* to_magic */
1101 _initialize_remote ()
1103 add_target (&remote_ops
);
1106 add_set_cmd ("remotedebug", no_class
, var_boolean
, (char *)&kiodebug
,
1107 "Set debugging of remote serial I/O.\n\
1108 When enabled, each packet sent or received with the remote target\n\
1109 is displayed.", &setlist
),