gdb_server: suggest user to prefer GDB extended mode

In case of GDB connection not using extended mode, issue a warning
message to suggest the user to switch using the extended mode.
Issue the message only once at each run of OpenOCD, to avoid too
much noise.
Update the documentation to suggest using extended mode.

Change-Id: I9326e84f748d5d7912d5a48f00f0fb541ca19221
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: http://openocd.zylin.com/5311
Tested-by: jenkins
Reviewed-by: Karl Palsson <karlp@tweak.net.au>

diff --git a/doc/openocd.texi b/doc/openocd.texi
index a0ce7e34956dfd703018b9c41bc8d63d2036a896..9f20e391d272230c199f2c77ced75213d85ab1f3 100644 (file)
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -10337,18 +10337,31 @@ OpenOCD can communicate with GDB in two ways:
 @item
 A socket (TCP/IP) connection is typically started as follows:
 @example
 @item
 A socket (TCP/IP) connection is typically started as follows:
 @example

-target remote localhost:3333
+target extended-remote localhost:3333

 @end example
 This would cause GDB to connect to the gdbserver on the local pc using port 3333.
 
 @end example
 This would cause GDB to connect to the gdbserver on the local pc using port 3333.
 

-It is also possible to use the GDB extended remote protocol as follows:
+The extended remote protocol is a super-set of the remote protocol and should
+be the preferred choice. More details are available in GDB documentation
+@url{https://sourceware.org/gdb/onlinedocs/gdb/Connecting.html}
+
+To speed-up typing, any GDB command can be abbreviated, including the extended
+remote command above that becomes:

 @example
 @example

-target extended-remote localhost:3333
+tar ext :3333

 @end example
 @end example

+
+@b{Note:} If any backward compatibility issue requires using the old remote
+protocol in place of the extended remote one, the former protocol is still
+available through the command:
+@example
+target remote localhost:3333
+@end example
+

 @item
 A pipe connection is typically started as follows:
 @example
 @item
 A pipe connection is typically started as follows:
 @example

-target remote | openocd -c "gdb_port pipe; log_output openocd.log"
+target extended-remote | openocd -c "gdb_port pipe; log_output openocd.log"

 @end example
 This would cause GDB to run OpenOCD and communicate using pipes (stdin/stdout).
 Using this method has the advantage of GDB starting/stopping OpenOCD for the debug
 @end example
 This would cause GDB to run OpenOCD and communicate using pipes (stdin/stdout).
 Using this method has the advantage of GDB starting/stopping OpenOCD for the debug


@@ -10370,7 +10383,7 @@ Most programs would be written into flash (address 0) and run from there.
 
 @example
 $ arm-none-eabi-gdb example.elf
 
 @example
 $ arm-none-eabi-gdb example.elf

-(gdb) target remote localhost:3333
+(gdb) target extended-remote localhost:3333

 Remote debugging using localhost:3333
 ...
 (gdb) monitor reset halt
 Remote debugging using localhost:3333
 ...
 (gdb) monitor reset halt


@@ -10505,7 +10518,7 @@ set remote interrupt-on-connect off
 If you switched gdb_memory_map off, you may want to setup GDB memory map
 manually or issue @command{set mem inaccessible-by-default off}
 
 If you switched gdb_memory_map off, you may want to setup GDB memory map
 manually or issue @command{set mem inaccessible-by-default off}
 

-Now you can issue GDB command @command{target remote ...} and inspect memory
+Now you can issue GDB command @command{target extended-remote ...} and inspect memory

 of a running target. Do not use GDB commands @command{continue},
 @command{step} or @command{next} as they synchronize GDB with your target
 and GDB would require stopping the target to get the prompt back.
 of a running target. Do not use GDB commands @command{continue},
 @command{step} or @command{next} as they synchronize GDB with your target
 and GDB would require stopping the target to get the prompt back.

diff --git a/src/server/gdb_server.c b/src/server/gdb_server.c
index 0e0b595c6982cccd1e20e9fe5e34a22709526715..17042fbf5ea350a0a886904da0ff358de8378c68 100644 (file)
--- a/src/server/gdb_server.c
+++ b/src/server/gdb_server.c
@@ -3228,6 +3228,7 @@ static int gdb_input_inner(struct connection *connection)
        int packet_size;
        int retval;
        struct gdb_connection *gdb_con = connection->priv;
        int packet_size;
        int retval;
        struct gdb_connection *gdb_con = connection->priv;

+       static bool warn_use_ext;

 
        target = get_target_from_connection(connection);
 
 
        target = get_target_from_connection(connection);
 


@@ -3304,6 +3305,12 @@ static int gdb_input_inner(struct connection *connection)
                                        break;
                                case '?':
                                        gdb_last_signal_packet(connection, packet, packet_size);
                                        break;
                                case '?':
                                        gdb_last_signal_packet(connection, packet, packet_size);

+                                       /* '?' is sent after the eventual '!' */
+                                       if (!warn_use_ext && !gdb_con->extended_protocol) {
+                                               warn_use_ext = true;
+                                               LOG_WARNING("Prefer GDB command \"target extended-remote %s\" instead of \"target remote %s\"",
+                                                                       connection->service->port, connection->service->port);
+                                       }

                                        break;
                                case 'c':
                                case 's':
                                        break;
                                case 'c':
                                case 's':