smp: deprecate legacy SMP core switching support

The deprecation was already in the documentation since v0.11.0
through commit 85ba2dc4c6 ("rtos/hwthread: add hardware-thread
pseudo rtos") but OpenOCD was not informing the user printing a
runtime message.

Remove the deprecated method from the documentation and print a
deprecated message at runtime.
There is no reliable way to print the same message in GDB console,
so we have to rely on user noticing it in the OpenOCD log.
Target is to remove the functionality after v0.12.0.

Change-Id: Idd2d9e3b6eccc92dcf0432c3c7de2f8a0fcabe9f
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: https://review.openocd.org/c/openocd/+/6862
Tested-by: jenkins

doc/openocd.texi

@@ -11568,57 +11568,6 @@ The @command{step} and @command{stepi} commands can be used to step a specific c
 while other cores are free-running or remain halted, depending on the
 scheduler-locking mode configured in GDB.
 
-@section Legacy SMP core switching support
-@quotation Note
-This method is deprecated in favor of the @emph{hwthread} pseudo RTOS.
-@end quotation
-
-For SMP support following GDB serial protocol packet have been defined :
-@itemize @bullet
-@item j - smp status request
-@item J - smp set request
-@end itemize
-
-OpenOCD implements :
-@itemize @bullet
-@item @option{jc} packet for reading core id displayed by
-GDB connection. Reply is @option{XXXXXXXX} (8 hex digits giving core id) or
- @option{E01} for target not smp.
-@item @option{JcXXXXXXXX} (8 hex digits) packet for setting core id displayed at next GDB continue
-(core id -1 is reserved for returning to normal resume mode). Reply @option{E01}
-for target not smp or @option{OK} on success.
-@end itemize
-
-Handling of this packet within GDB can be done :
-@itemize @bullet
-@item by the creation of an internal variable (i.e @option{_core}) by mean
-of function allocate_computed_value allowing following GDB command.
-@example
-set $_core 1
-#Jc01 packet is sent
-print $_core
-#jc packet is sent and result is affected in $
-@end example
-
-@item by the usage of GDB maintenance command as described in following example (2 cpus in SMP with
-core id 0 and 1 @pxref{definecputargetsworkinginsmp,,Define CPU targets working in SMP}).
-
-@example
-# toggle0 : force display of coreid 0
-define toggle0
-maint packet Jc0
-continue
-main packet Jc-1
-end
-# toggle1 : force display of coreid 1
-define toggle1
-maint packet Jc1
-continue
-main packet Jc-1
-end
-@end example
-@end itemize
-
 @node Tcl Scripting API
 @chapter Tcl Scripting API
 @cindex Tcl Scripting API

src/server/gdb_server.c

@@ -3657,12 +3657,14 @@ static int gdb_input_inner(struct connection *connection)
 					break;
 
 				case 'j':
+					/* DEPRECATED */
 					/* packet supported only by smp target i.e cortex_a.c*/
 					/* handle smp packet replying coreid played to gbd */
 					gdb_read_smp_packet(connection, packet, packet_size);
 					break;
 
 				case 'J':
+					/* DEPRECATED */
 					/* packet supported only by smp target i.e cortex_a.c */
 					/* handle smp packet setting coreid to be played at next
 					 * resume to gdb */

src/target/smp.c

@@ -28,6 +28,7 @@
 #include "smp.h"
 #include "helper/binarybuffer.h"
 
+/* DEPRECATED: gdb_read_smp_packet/gdb_write_smp_packet to be removed      */
 /*  implementation of new packet in gdb interface for smp feature          */
 /*                                                                         */
 /*   j : smp  status request                                               */
@@ -53,11 +54,15 @@
 /*  maint packet jc                                                        */
 
 /* packet j :smp status request */
+#define DEPRECATED_MSG "DEPRECATED: This method is deprecated in favor of the hwthread pseudo RTOS"
 int gdb_read_smp_packet(struct connection *connection,
 		char const *packet, int packet_size)
 {
 	struct target *target = get_target_from_connection(connection);
 	int retval = ERROR_OK;
+
+	LOG_WARNING(DEPRECATED_MSG);
+
 	if (target->smp) {
 		if (strncmp(packet, "jc", 2) == 0) {
 			const uint32_t len = sizeof(target->gdb_service->core[0]);
@@ -83,6 +88,8 @@ int gdb_write_smp_packet(struct connection *connection,
 	int coreid = 0;
 	int retval = ERROR_OK;
 
+	LOG_WARNING(DEPRECATED_MSG);
+
 	/* skip command character */
 	if (target->smp) {
 		if (strncmp(packet, "Jc", 2) == 0) {

src/target/smp.h

@@ -30,8 +30,10 @@
 
 extern const struct command_registration smp_command_handlers[];
 
+/* DEPRECATED */
 int gdb_read_smp_packet(struct connection *connection,
 		char const *packet, int packet_size);
+/* DEPRECATED */
 int gdb_write_smp_packet(struct connection *connection,
 		char const *packet, int packet_size);